Metadata-Version: 2.4
Name: fitron
Version: 1.1.0
Summary: FITRON: adaptive fuzzy-tree MCDM decision engine for generic tabular binary problems
Author: zibransheikh, hazlived
License-Expression: MIT
Project-URL: Homepage, https://github.com/hazlived/fitron
Project-URL: Issues, https://github.com/hazlived/fitron/issues
Keywords: fitron,fuzzy,decision-tree,mcdm,topsis,adaptive,tabular,binary-classification
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.4
Requires-Dist: pandas>=2.1
Requires-Dist: scikit-learn>=1.4
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# FITRON

[![PyPI version](https://img.shields.io/pypi/v/fitron.svg)](https://pypi.org/project/fitron/)
[![Python](https://img.shields.io/pypi/pyversions/fitron.svg)](https://pypi.org/project/fitron/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Repository](https://img.shields.io/badge/GitHub-hazlived%2Ffitron-black.svg)](https://github.com/hazlived/fitron)

FITRON is a Python library for ranking-first decision intelligence on tabular binary problems.

Instead of stopping at yes/no prediction, FITRON combines classification quality and multi-criteria ranking so you can prioritize records with interpretable, feature-level explanations.

Current release: `1.1.0`

- PyPI: https://pypi.org/project/fitron/
- Repository: https://github.com/hazlived/fitron

## Table of Contents

- [Why FITRON](#why-fitron)
- [Key Features](#key-features)
- [Theoretical Foundations & Guarantees](#theoretical-foundations--guarantees)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core API](#core-api)
- [Function Reference](#function-reference)
- [Coding Guide](#coding-guide)
- [Common Workflows](#common-workflows)
- [Testing and Development](#testing-and-development)
- [Troubleshooting](#troubleshooting)
- [License](#license)

## Why FITRON

Many production pipelines output only probabilities or binary labels. FITRON adds a ranking layer designed for operational decision flows where prioritization matters.

FITRON integrates:

1. Fuzzy feature transformation for smoother numeric representation.
2. Decision-tree backbone for robust tabular performance and feature importance.
3. TOPSIS multi-criteria ranking for transparent candidate prioritization.
4. Memory-guided adaptive weights for iterative refinement.

## Key Features

- **Ranking-first Decision Intelligence**: Operational candidate prioritization combining calibrated class confidence with multi-criteria MCDM utility.
- **Provable Simplex Optimization**: Exact $\mathcal{O}(m \log m)$ Euclidean projection onto probability simplex $\Delta^{m-1}$, replacing unconstrained heuristic search.
- **Strict Ruspini Quantile Partitions**: Proved partition-of-unity completeness ($\sum \mu_k(x) \equiv 1.0$) with indicator handling for categorical and discrete features.
- **Vectorized Bounded TOPSIS**: Relative closeness scores mathematically bounded in $[0, 1]$ with global data-driven criteria orientation.
- **Adaptive Memory & Concept Drift Tracking**: A-EWMA criteria weighting with Wasserstein-1 drift distance and recency decay.
- **Interpretable Explanations**: Transparent feature-level contribution metrics mapping directly back to original business attributes.
- **Practical Deployment Safeguards**: Dynamic confidence-floor fallback, Platt/Isotonic calibration, and automated balanced accuracy threshold tuning.

## Theoretical Foundations & Guarantees

FITRON is underpinned by four rigorous mathematical theorems:

1. **Theorem 1 (Resolution of Ranking Degeneracy)**: Demonstrates that under homogeneous positive candidate slices ($y_i = 1$), binary NDCG and AP yield zero gradient ($\\nabla_{\\mathbf{w}} Q_{rank} = \\mathbf{0}$). FITRON introduces **Graded Operational Ground-Truth Utility** $g_i = y_i \\cdot \\psi(\\mathbf{u}_i)$ (where $\\psi$ measures real-world impact such as financial loss exposure, CVSS severity, or machine downtime), recovering strictly monotonic ranking gradients.
2. **Theorem 2 (Ruspini Fuzzy Partition Completeness)**: Formulates quantile membership functions $\\mu_{low}, \\mu_{mid}, \\mu_{high}$ and proves $\\sum_{k \\in \\{low, mid, high\\}} \\mu_k(x) = 1.0$ for all $x \\in \\mathbb{R}$. Features with degenerate quantile knots ($q_{25} = q_{75}$) are handled via exact indicator functions.
3. **Theorem 3 (TOPSIS Boundedness)**: Proves that for all normalized fuzzy decision matrices, the relative closeness score $C_i = \\frac{D_i^-}{D_i^+ + D_i^-}$ is strictly bounded within $[0, 1]$ and reaches extremities only on ideal or anti-ideal alternatives.
4. **Theorem 4 (Exact Euclidean Simplex Projection)**: Guarantees that weight updates are projected exactly onto the standard probability simplex $\\Delta^{m-1} = \\{\\mathbf{w} \\in \\mathbb{R}^m : \\sum w_j = 1, w_j \\ge 0\\}$ in $\\mathcal{O}(m \\log m)$ time using the Michelot-Duchi projection algorithm.

## Installation

### End users

```bash
python -m pip install -U fitron
```

### From source

```bash
git clone https://github.com/hazlived/fitron.git
cd fitron
python -m pip install -U pip setuptools wheel
python -m pip install .
```

### Editable install (development)

```bash
python -m pip install -U pip setuptools wheel
python -m pip install -e .[dev]
```

### Verify installation

```bash
python -c "import fitron; from fitron import FITRONModel; print('fitron import OK')"
```

## Quick Start

Use this sequence for a reliable first run.

1. Install FITRON:

```bash
python -m pip install -U fitron
```

2. Run a minimal end-to-end example:

```python
import pandas as pd
from fitron import FITRONModel

sample = pd.DataFrame(
    {
        "income": [50000, 20000, 75000, 43000, 60000, 47000, 71000, 25000, 55000, 38000, 65000, 30000],
        "risk": [0.2, 0.8, 0.3, 0.5, 0.4, 0.6, 0.25, 0.9, 0.35, 0.7, 0.2, 0.75],
        "credit_score": [710, 520, 760, 640, 700, 650, 750, 500, 720, 580, 740, 550],
        "employment_years": [5, 1, 10, 3, 7, 4, 9, 1, 6, 2, 8, 2],
        "target": [1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 0],
    }
)

model = FITRONModel(iterations=5, random_state=42)
result = model.fit(sample, target="target")

print("Best candidate index:", result.best_index)
print("Best score:", round(float(result.best_score), 4))
print("Test accuracy:", round(float(result.test_accuracy), 4))
print("\nExplanation:")
for item in result.explanation:
    print(" -", item)
```

3. Optional, from repository root:

```bash
python examples/run_demo.py
```

Expected behavior: prints best candidate index, score, train/test accuracy, and explanation lines.

## Core API

### Class API

#### `FITRONModel`

Main iterative model for fit-rank-explain workflows.

Constructor:

```python
FITRONModel(
    iterations=20,
    random_state=42,
    decision_threshold=0.5,
    objective_classification_weight=0.65,
    confidence_floor=0.55,
)
```

Primary methods:

- `fit(df, target, ...)` -> train and optimize over iterations.
- `rank(df, target, ...)` -> score/rank using current learned state.
- `explain()` -> explanation list from last run.

### Functional API

- `fit(df, target, ...)`
- `rank(df, target, weights=None, memory=None, ...)`
- `explain(result)`
- `update_memory(memory, weights, score, best_idx)`

### Returned result object

`fit()` and `rank()` return `IterationResult`, including:

- predictions and ranking scores
- candidate indices and best index
- objective/classification/ranking quality metrics
- train/test accuracy and threshold metrics
- final weights and explanation list

## Function Reference

Use this table as a fast lookup for what each public entry point does.

| Function / Method | Input | Output | What it does | Use when |
|---|---|---|---|---|
| `FITRONModel(...)` | tuning parameters | model instance | Configures iterative FITRON engine state. | You need reusable model state across multiple runs. |
| `FITRONModel.fit(df, target, ...)` | training dataframe + target | `IterationResult` | Trains and optimizes ranking/classification over iterations. | First pass on a dataset; baseline + learned weights. |
| `FITRONModel.rank(df, target, ...)` | dataframe + target + existing model state | `IterationResult` | Ranks using learned memory/weights with optional retuning. | Re-ranking new candidate batches after initial fit. |
| `FITRONModel.explain()` | none | `list[str]` | Returns explanation entries from the latest model run. | You want quick explanation access from the model instance. |
| `fit(df, target, ...)` | dataframe + target | `IterationResult` | One-shot convenience wrapper around class workflow. | Fast scripting without managing class lifecycle. |
| `rank(df, target, weights=None, memory=None, ...)` | dataframe + target + optional state | `IterationResult` | One-shot ranking call with optional prior state injection. | Stateless pipelines or external state management. |
| `explain(result)` | `IterationResult` | `list[str]` | Extracts explanation strings from a run result. | You already have a result object and need text explanation. |
| `update_memory(memory, weights, score, best_idx)` | memory + optimization stats | `None` | Updates memory history and best-known weight trajectory. | Manual/custom control loops around FITRON logic. |

## Coding Guide

This is the recommended implementation pattern for production-style usage.

1. Define your tabular schema and map the target to binary values.
2. Start with conservative defaults (`iterations=10-20`, `random_state=42`).
3. Run `fit()` once and log metrics for calibration.
4. Use `rank()` for future batches while reusing model state.
5. Persist and monitor threshold/F1/balanced-accuracy trends.
6. Tune `decision_threshold`, `confidence_floor`, and `iterations` only after metric review.

Reference skeleton:

```python
from fitron import FITRONModel

# 1) Create model once
model = FITRONModel(
    iterations=20,
    random_state=42,
    decision_threshold=0.5,
    confidence_floor=0.55,
)

# 2) Initial training + ranking
train_result = model.fit(
    df=train_df,
    target="decision",
    target_map={"reject": 0, "approve": 1},
    metrics_output_path="./iteration_metrics.csv",
)

# 3) Operational ranking on new data
batch_result = model.rank(
    df=batch_df,
    target="decision",
    target_map={"reject": 0, "approve": 1},
)

# 4) Surface result for downstream systems
best_idx = batch_result.best_index
best_score = float(batch_result.best_score)
explanation = batch_result.explanation
```

Production notes:

- Keep `target_map` explicit for string labels to avoid silent mapping mistakes.
- Prefer class API for long-running services so memory/weights evolve consistently.
- Export iteration metrics in CI/staging and compare drift before changing thresholds.

## Common Workflows

### String target mapping

```python
from fitron import fit

result = fit(
    df=data,
    target="decision",
    target_map={"reject": 0, "approve": 1},
    iterations=10,
)
```

### Save per-iteration metrics

```python
from fitron import FITRONModel

model = FITRONModel(iterations=20)
result = model.fit(
    df=data,
    target="decision",
    metrics_output_path="./iteration_metrics.csv",
)
```

### Multi-pass refinement

```python
from fitron import FITRONModel

model = FITRONModel(iterations=5, random_state=42)
first = model.fit(train_data, target="decision")
second = model.rank(new_data, target="decision")
```

## Testing and Development

Run tests:

```bash
pytest -q
```

Release notes: [CHANGELOG.md](CHANGELOG.md)

## Troubleshooting

### `ModuleNotFoundError: No module named 'fitron'`

Cause: package installed in a different interpreter than the one running your command.

Fix:

```bash
python -c "import sys; print(sys.executable)"
python -m pip install -U fitron
```

### NumPy/Pandas build errors on Windows

Cause: non-standard Python distributions may miss compatible wheels and try source builds.

Fix:

- Use standard CPython from python.org.
- Create a fresh virtual environment.
- Install with that venv interpreter directly.

```powershell
python -m venv .venv-win
.\.venv-win\Scripts\python.exe -m pip install -U pip
.\.venv-win\Scripts\python.exe -m pip install -U fitron
```

### Poor ranking quality or frequent fallback

- Increase dataset size and feature quality.
- Verify `target_map` for string labels.
- Tune `decision_threshold` and `confidence_floor`.
- Increase `iterations` for more adaptive refinement.

## License

MIT
