Metadata-Version: 2.4
Name: aidflow
Version: 3.0.7
Summary: Pipeline execution framework
Project-URL: Homepage, https://github.com/aigensys-labs/aidflow
Project-URL: Documentation, https://aidflow.aigensys.com/
Project-URL: Repository, https://github.com/aigensys-labs/aidflow
Project-URL: Bug Tracker, https://github.com/aigensys-labs/aidflow/issues
Author-email: AIGENSYS <info@aigensys.com>
License: FSL-1.1-Apache-2.0
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
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?cache=300&color=blue)](https://pypi.org/project/aidflow/)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/aidflow/)
[![License](https://img.shields.io/badge/License-FSL--1.1-blue.svg)](https://fsl.software/)
[![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.

---

## The Three-Layer Abstraction (The "Super-Gear")

AIDflow decouples the user's intent from the mathematical execution using a three-layer stack. This allows us to change the underlying ML algorithm without ever breaking the User Interface.

### Layer 1: The Worker (Interface)
*   **Role:** The Orchestrator.
*   **Responsibility:** Handles UI, input validation, and state registration.
*   **User Experience:** *"I want to clean my data"* → `ctx.data.fe_cleaner()`.

### Layer 2: The Model (The Gear)
*   **Role:** The Adapter.
*   **Responsibility:** Decouples the Worker from the Fitter. It manages "Fit Options," allowing a single Worker to support multiple different algorithms (e.g., switching between a Sparse GLM and an ElasticNet).

### Layer 3: The Fitter (The Engine)
*   **Role:** The Compute Engine.
*   **Responsibility:** Pure mathematical execution. This is where the actual matrix multiplication, optimization, and fitting occur. It has no knowledge of the UI or the Project Context—it only knows data and parameters.

---

## 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.workers.data_loader.fitters[0]
prm = dict(
    low_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)
```