Metadata-Version: 2.4
Name: aidflow
Version: 3.0.1
Summary: Pipeline execution framework
Author-email: AIGENSYS <info@aigensys.com>
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# AIDflow

**Human-in-the-Loop Scorecard Orchestration for Regulated ML**

[![PyPI version](https://img.shields.io/pypi/v/aidflow.svg?color=blue)](https://pypi.org/project/aidflow/)
[![Python Version](https://img.shields.io/pypi/pyversions/aidflow.svg)](https://pypi.org/project/aidflow/)
[![License](https://img.shields.io/badge/License-Custom-informational.svg)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

---

Most automated machine learning tools act as black-box wrappers—they optimize metrics in isolation while hiding the underlying logic, producing models that risk failure during regulatory scrutiny. **AIDflow is built differently.**

Designed specifically for high-stakes, highly regulated industries (**Fintech, Banking, Insurance**), AIDflow treats machine learning models not as opaque binary artifacts, but as **auditable, legal assets**. It provides a comprehensive ecosystem for scorecard development built around **Human-in-the-Loop Governance**.

---

## 🏛️ Core Pillars

### 🎯 Absolute Micromanagement
Automation should never mean a loss of control. While AIDflow automates repetitive pipeline mechanics, every layer remains fully transparent and configurable. 
Practitioners can pause execution, inspect intermediate states, and fine-tune parameters—from raw feature ingestion and binning to final champion model selection.

### 📋 Audit-Ready Reporting
Every execution phase generates comprehensive, standardized documentation out of the box. 
AIDflow goes beyond traditional accuracy metrics ($AUC$, $Gini$) to produce full validation artifacts required by internal risk committees and external financial regulators.

### 🛡️ Production Scorecard Readiness
Outputs extend far beyond standard estimator binaries (`.pkl` / `.joblib`). AIDflow generates fully engineered production scorecards complete with Population Stability Index ($PSI$), 
Characteristic Stability Index ($CSI$), score transformations, and feature explainability vectors that satisfy international credit risk standards (e.g., Basel II/III, IFRS 9).

### ⚡ Bridging the Governance Gap
AIDflow eliminates the friction between rapid experimental prototyping and enterprise compliance—ensuring models that perform in a Jupyter notebook transition seamlessly into compliant production environments.

---

## 🚀 Quick Start

### Installation

```bash
pip install aidflow
```

### Basic Usage

Defining the Project Context (Control Plane) & Project Scope:

```python
import aidflow as aid

ctx = aid.ProjectContext()

ctx.genesis(
project      = 'test',
input_data   = 'test.csv',
target       = 'target',
yy_mm        = 'decision_date',
yy_mm_format = '%d%b%y'
)
ctx.params()
```

**Worker → Model**

Accessing worker's inputs schema → parameters & types:

```python        
ctx.workers.data_loader.inputs
```

Accessing worker's fitter options and schema → parameters & types:

```python        
ctx.workers.data_loader.fitters
```    

Executing worker with defaults → auto provided by the context:

```python        
ctx.workers.data_loader()
```

Once worker has been executed, thus its main model has been built,\
we have access to all populated attributes.

```python   
ctx.workers.data_loader.inputs.inputs
ctx.workers.data_loader.result
ctx.workers.data_loader.state
ctx.workers.data_loader.features
ctx.workers.data_loader.stats
ctx.workers.data_loader.params
ctx.workers.data_loader.fitter  # jump to chosen internal fitter
...
```

View to model report of executed worker:

```python
ctx.workers.data_loader.report.show()
```

**Model → Fitter**

Once worker has been executed, we obtain internal fitter state\
and its parametrization:

```python        
ctx.workers.data_loader.fitter
```

The fitted fitter provides all populated attributes.

```python        
ctx.workers.data_loader.fitter.stats
ctx.workers.data_loader.fitter.params
```

Direct choice and parametrization of internal fitter:

```python
fx  = ctx.registry.data_loader[0]
prm = dict(
flow_vars = ['target1', 'target2'],
columns_subset = ['fe1', 'fe2']
)
loader = ctx.workers.data_loader(fx_choice = fx, fx_params = prm)
```

In the experimenting phase when various targets might be under testing\
(*note that target2 must be present in the data*):

```python
cfg = dict(
target = 'target2',
)
woe =  ctx.workers.data_loader(fx_config = cfg)
```

### Pipeline Architecture
[ Raw Data Ingestion ] 
        │
        ▼
[ Feature Binning & WOE Transformation ]  ──► (Human-in-the-Loop Adjustments)
        │
        ▼
[ Multi-Constraint Feature Selection ]    ──► (PSI / Monotonicity Filtering)
        │
        ▼
[ Scorecard Scaling & Alignment ]         ──► (Points to Double Odds Setup)
        │
        ▼
[ Audit Report & Model Artifacts ]        ──► (Compliance PDF & Production Rules)