feat: new minimal api

Author: ElouenGinat

README.md

@@ -2,132 +2,155 @@
 
 **Optimal Binning Histograms for Python**
 
-Khisto is a Python library for creating histograms and cumulative distribution functions (ECDFs) using the **Khiops optimal binning algorithm**. Unlike standard histograms that use fixed-width bins or simple heuristics, Khisto automatically determines the optimal number of bins and their variable widths to best represent the underlying data distribution.
-
-It provides a core Array API for data analysis and drop-in replacements for **Matplotlib** and **Plotly** plotting functions.
+Khisto is a Python library for creating histograms using the **Khiops optimal binning algorithm**. Unlike standard histograms that use fixed-width bins or simple heuristics, Khisto automatically determines the optimal number of bins and their variable widths to best represent the underlying data distribution.
 
 ## Features
 
 - **Optimal Binning**: Uses the MODL (Minimum Description Length) principle to find the best discretization.
 - **Variable-Width Bins**: Captures dense regions with fine bins and sparse regions with wider bins.
-- **Array API Support**: Works with NumPy, PyTorch, JAX, CuPy, and more (via `narwhals` and `array-api-compat`).
-- **Plotting Integrations**:
-  - **Matplotlib**: `khisto.matplotlib.hist` (drop-in replacement for `plt.hist`)
-  - **Plotly**: `khisto.plotly.histogram` (compatible with Plotly Express)
+- **NumPy Compatible**: Drop-in replacement for `numpy.histogram`.
+- **Matplotlib Integration**: `khisto.matplotlib.hist` works like `plt.hist`.
+- **Minimal Dependencies**: Only requires NumPy (matplotlib optional for plotting).
 
 ## Installation
 
-### From PyPI
-
-Install the core library:
-
 ```bash
 pip install khisto
 ```
 
-Install with plotting support:
+With matplotlib support:
 
 ```bash
-# For Matplotlib support
 pip install "khisto[matplotlib]"
-
-# For Plotly support
-pip install "khisto[plotly]"
-
-# For everything
-pip install "khisto[all]"
 ```
 
-## Usage
-
-### 1. Core Array API
+## Quick Start
 
-Compute optimal histograms and ECDFs directly from arrays.
+### NumPy-like API
 
 ```python
 import numpy as np
-from khisto.array import histogram, ecdf
+from khisto import histogram
 
 # Generate data
 data = np.random.normal(0, 1, 1000)
 
-# Compute optimal histogram (returns density values and bin edges)
-values, edges = histogram(data, granularity="best")
+# Compute optimal histogram (drop-in replacement for np.histogram)
+hist, bin_edges = histogram(data)
 
-# Compute ECDF
-cdf = ecdf(data)
-print(cdf(0.0))  # Evaluate CDF at x=0
-```
+# With density normalization
+density, bin_edges = histogram(data, density=True)
+
+# Limit maximum number of bins
+hist, bin_edges = histogram(data, max_bins=10)
 
-### 2. Matplotlib Integration
+# Specify range
+hist, bin_edges = histogram(data, range=(-2, 2))
+```
 
-Use Khisto as a drop-in replacement for `plt.hist`.
+### Matplotlib Integration
 
 ```python
-import matplotlib.pyplot as plt
-import khisto.matplotlib as khm
 import numpy as np
+import matplotlib.pyplot as plt
+from khisto.matplotlib import hist
 
 data = np.random.normal(0, 1, 1000)
 
-# Standard Matplotlib histogram
-# plt.hist(data, bins=30)
-
-# Khisto optimal histogram
-khm.hist(data, density=True)
+# Create optimal histogram plot
+n, bins, patches = hist(data)
+plt.show()
 
+# With density
+n, bins, patches = hist(data, density=True)
+plt.xlabel('Value')
+plt.ylabel('Density')
 plt.show()
 ```
 
-### 3. Plotly Integration
+## API Reference
 
-Create interactive histograms with optimal binning.
+### `khisto.histogram`
 
 ```python
-import plotly.express as px
-import khisto.plotly as khp
+def histogram(
+    a: ArrayLike,
+    range: Optional[tuple[float, float]] = None,
+    max_bins: Optional[int] = None,
+    density: bool = False,
+) -> tuple[ndarray, ndarray]
+```
+
+Compute an optimal histogram using the Khiops binning algorithm.
 
-df = px.data.tips()
+**Parameters:**
+- `a`: Input data. The histogram is computed over the flattened array.
+- `range`: The lower and upper range of the bins. Values outside are ignored.
+- `max_bins`: Maximum number of bins. If None, the algorithm selects optimal.
+- `density`: If True, return probability density. If False, return counts.
 
-# Create histogram
-fig = khp.histogram(df, x="total_bill", color="sex")
-fig.show()
+**Returns:**
+- `hist`: The values of the histogram (counts or density).
+- `bin_edges`: The bin edges (length = len(hist) + 1).
+
+### `khisto.matplotlib.hist`
+
+```python
+def hist(
+    x: ArrayLike,
+    range: Optional[tuple[float, float]] = None,
+    max_bins: Optional[int] = None,
+    density: bool = False,
+    histtype: str = "bar",
+    orientation: Literal["vertical", "horizontal"] = "vertical",
+    log: bool = False,
+    color: Optional[str] = None,
+    label: Optional[str] = None,
+    ax: Optional[Axes] = None,
+    **kwargs,
+) -> tuple[ndarray, ndarray, Any]
 ```
 
-## Development
+Plot an optimal histogram using matplotlib.
+
+**Parameters:**
+- `x`: Input data.
+- `range`: The lower and upper range of the bins.
+- `max_bins`: Maximum number of bins.
+- `density`: If True, plot probability density.
+- `histtype`: Type of histogram (`"bar"`, `"step"`, `"stepfilled"`).
+- `orientation`: `"vertical"` or `"horizontal"`.
+- `log`: If True, set log scale on the value axis.
+- `ax`: Matplotlib axes to plot on.
+
+**Returns:**
+- `n`: The histogram values.
+- `bins`: The bin edges.
+- `patches`: The matplotlib patches.
 
-This project uses [uv](https://github.com/astral-sh/uv) for dependency management and packaging.
+## How It Works
 
-### Installation from Source
+Khisto uses the Khiops optimal binning algorithm based on the MODL (Minimum Optimal Description Length) principle. Instead of using fixed-width bins like traditional histograms, it:
 
-1.  **Install uv**:
-    ```bash
-    curl -LsSf https://astral.sh/uv/install.sh | sh
-    ```
+1. Analyzes the data distribution
+2. Finds bin boundaries that minimize information loss
+3. Creates variable-width bins that adapt to data density
 
-2.  **Clone the repository**:
-    ```bash
-    git clone https://github.com/yourusername/khisto-python.git
-    cd khisto-python
-    ```
+This results in histograms that better represent the underlying distribution, with finer bins in dense regions and wider bins in sparse regions.
 
-3.  **Sync dependencies**:
-    Create a virtual environment and install all dependencies (including dev and optional extras):
-    ```bash
-    uv sync --all-extras
-    ```
+## Development
 
-4.  **Run Tests**:
-    ```bash
-    uv run pytest
-    ```
+```bash
+# Clone repository
+git clone https://github.com/khiops/khisto-python.git
+cd khisto-python
 
-### Project Structure
+# Install with dev dependencies
+pip install -e ".[matplotlib]"
 
-- `src/khisto/array`: Core algorithms and Array API.
-- `src/khisto/matplotlib`: Matplotlib plotting backends.
-- `src/khisto/plotly`: Plotly plotting backends.
-- `src/khiops`: C++ backend source (requires CMake to build if modifying).
+# Run tests
+pytest
+```
 
 ## License