meerax 1.0.0__tar.gz

meerax-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sameer Maurya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meerax-1.0.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: meerax
+Version: 1.0.0
+Summary: Shared ML utilities — LLM providers, evaluation metrics, visualization, and report generation for Sameer Maurya's projects and organization.
+Author: Sameer Maurya
+License: MIT
+Project-URL: Homepage, https://github.com/mauryasameer/the-forge
+Project-URL: Repository, https://github.com/mauryasameer/the-forge
+Project-URL: Issues, https://github.com/mauryasameer/the-forge/issues
+Project-URL: Changelog, https://github.com/mauryasameer/the-forge/blob/main/CHANGELOG.md
+Keywords: machine-learning,llm,evaluation,visualization
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: scikit-learn>=1.4
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == "llm"
+Requires-Dist: openai>=1.55; extra == "llm"
+Requires-Dist: ollama>=0.3; extra == "llm"
+Provides-Extra: stats
+Requires-Dist: statsmodels>=0.14; extra == "stats"
+Provides-Extra: nlp
+Requires-Dist: nltk>=3.9; extra == "nlp"
+Provides-Extra: imbalance
+Requires-Dist: imbalanced-learn>=0.12; extra == "imbalance"
+Provides-Extra: vision
+Requires-Dist: torch>=2.2; extra == "vision"
+Requires-Dist: torchvision>=0.17; extra == "vision"
+Requires-Dist: pillow>=10.2; extra == "vision"
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=15; extra == "parquet"
+Provides-Extra: all
+Requires-Dist: meerax[llm]; extra == "all"
+Requires-Dist: meerax[stats]; extra == "all"
+Requires-Dist: meerax[nlp]; extra == "all"
+Requires-Dist: meerax[imbalance]; extra == "all"
+Requires-Dist: meerax[vision]; extra == "all"
+Requires-Dist: meerax[parquet]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: ruff==0.11.13; extra == "dev"
+Dynamic: license-file
+
+# meerax
+
+![Version](https://img.shields.io/badge/version-1.0.0-c8a96e)
+![Python](https://img.shields.io/badge/python-3.12-00e5cc)
+![License](https://img.shields.io/badge/license-MIT-informational)
+
+Shared ML utilities — LLM providers, evaluation metrics, visualization, and report generation.
+Used as an in-house dependency across all of Sameer Maurya's ML projects and organization.
+Source repo: [the-forge](https://github.com/mauryasameer/the-forge) — kept its original name;
+only the installable package was renamed to `meerax`.
+
+## Install
+
+```bash
+pip install git+https://github.com/mauryasameer/the-forge.git@v1.0.0
+```
+
+Or pin in `requirements.txt`:
+
+```
+meerax @ git+https://github.com/mauryasameer/the-forge.git@v1.0.0
+```
+
+Once published to PyPI, this becomes `pip install meerax` / `meerax==1.0.0`.
+
+## Modules
+
+| Module | What it gives you |
+|---|---|
+| `meerax.llm` | Swap-in LLM backends — Claude, OpenAI, Ollama behind one interface, text or images |
+| `meerax.eval.classification` | F1, AUC-ROC, precision, recall in one call |
+| `meerax.eval.timeseries` | RMSE, MAPE, SMAPE, ADF stationarity test |
+| `meerax.eval.text` | BLEU-4, ROUGE-L for caption / summary quality |
+| `meerax.viz` | Dark-themed matplotlib plots (confusion matrix, ROC, forecast, decomposition) |
+| `meerax.data` | CSV/parquet loaders with schema validation, stratified + time splits, SMOTE |
+| `meerax.report` | Self-contained dark-themed HTML model-card report builder |
+| `meerax.logging` | One-call structured logger factory |
+| `meerax.vision` | Image folder dataset loader (PyTorch) + translation-grid plotting (torch or numpy/TF images) |
+
+## Scaffolding Projects
+
+Every project in the ecosystem follows the same PROJECT_STANDARDS.md layout and depends on
+`meerax`. The `meerax` CLI (installed alongside the package) generates or retrofits that layout:
+
+```bash
+# brand-new project
+meerax new my-project --path ~/dev
+
+# retrofit an existing, non-empty directory — additive only, never overwrites
+cd ~/dev/my-existing-notebook-project
+meerax init
+```
+
+`meerax new` creates the full `src/{core,providers,services,utils,data}` + `tests/` + CI
+skeleton, pins `requirements.txt` to the current `meerax` release, and runs `git init`.
+
+`meerax init` fills in whatever's missing from that same layout without touching files that
+already exist, and reports any top-level files it doesn't recognize (e.g. notebooks) so you can
+move them into `src/` by hand.
+
+## Quick Start
+
+```python
+from meerax.llm import ClaudeProvider, PromptTemplate
+from meerax.eval import evaluate_classifier
+from meerax.viz import apply_meerax_theme
+from meerax.report import ReportBuilder, ReportSection
+
+# LLM: swap provider without changing downstream code
+llm = ClaudeProvider()                         # or OpenAIProvider() / OllamaProvider()
+tpl = PromptTemplate("Explain {finding} to a risk manager in 3 sentences.")
+response = llm.generate(tpl.render(finding="high AUC-ROC with low recall"))
+
+# Eval
+metrics = evaluate_classifier(y_true, y_pred, y_prob=probabilities)
+print(metrics)
+# Accuracy : 0.9823
+# F1       : 0.8741
+# AUC-ROC  : 0.9912
+
+# Viz + Report
+apply_meerax_theme()
+rb = ReportBuilder("Fraud Detection — Model Report v0.1.0")
+rb.add_section(ReportSection(
+    title="Performance",
+    metrics=metrics.to_dict(),
+    content=response.content,
+))
+rb.save("reports/model_report.html")
+```
+
+## LLM Provider Interface
+
+All providers implement `LLMProvider.generate()` and `.chat()`. Swap with one line:
+
+```python
+from meerax.llm import ClaudeProvider, OpenAIProvider, OllamaProvider
+
+llm = ClaudeProvider()    # needs ANTHROPIC_API_KEY
+llm = OpenAIProvider()    # needs OPENAI_API_KEY
+llm = OllamaProvider()    # needs Ollama running locally
+```
+
+## Benchmarks
+
+Self-contained benchmark scripts in `benchmarks/`:
+
+| Script | Description |
+|---|---|
+| `kv_cache_benchmark.py` | KV caching simulation at GPT-2 Medium scale |
+
+## Project Structure
+
+```
+the-forge/
+├── meerax/              # Installable package
+│   ├── llm/            # LLM provider abstraction
+│   ├── eval/            # Evaluation metrics
+│   ├── viz/             # Visualization utilities
+│   ├── data/            # Data loading, splitting, resampling
+│   ├── report/          # HTML report builder
+│   ├── scaffold/        # Project skeleton templates + create/retrofit logic
+│   ├── cli.py           # `meerax new` / `meerax init` command entry point
+│   ├── vision/          # Image dataset loader + translation-grid plotting
+│   └── logging.py       # Structured logger
+├── benchmarks/          # Standalone ML benchmark scripts
+├── tests/
+│   └── unit/            # 80 unit tests, zero external deps
+├── LICENSE
+├── pyproject.toml
+├── requirements.txt
+└── VERSION
+```
+
+---
+
+[sameer-portfolio](https://github.com/mauryasameer/sameer-portfolio) · [mauryasameer.com](https://www.mauryasameer.com)

meerax-1.0.0/README.md

@@ -0,0 +1,137 @@
+# meerax
+
+![Version](https://img.shields.io/badge/version-1.0.0-c8a96e)
+![Python](https://img.shields.io/badge/python-3.12-00e5cc)
+![License](https://img.shields.io/badge/license-MIT-informational)
+
+Shared ML utilities — LLM providers, evaluation metrics, visualization, and report generation.
+Used as an in-house dependency across all of Sameer Maurya's ML projects and organization.
+Source repo: [the-forge](https://github.com/mauryasameer/the-forge) — kept its original name;
+only the installable package was renamed to `meerax`.
+
+## Install
+
+```bash
+pip install git+https://github.com/mauryasameer/the-forge.git@v1.0.0
+```
+
+Or pin in `requirements.txt`:
+
+```
+meerax @ git+https://github.com/mauryasameer/the-forge.git@v1.0.0
+```
+
+Once published to PyPI, this becomes `pip install meerax` / `meerax==1.0.0`.
+
+## Modules
+
+| Module | What it gives you |
+|---|---|
+| `meerax.llm` | Swap-in LLM backends — Claude, OpenAI, Ollama behind one interface, text or images |
+| `meerax.eval.classification` | F1, AUC-ROC, precision, recall in one call |
+| `meerax.eval.timeseries` | RMSE, MAPE, SMAPE, ADF stationarity test |
+| `meerax.eval.text` | BLEU-4, ROUGE-L for caption / summary quality |
+| `meerax.viz` | Dark-themed matplotlib plots (confusion matrix, ROC, forecast, decomposition) |
+| `meerax.data` | CSV/parquet loaders with schema validation, stratified + time splits, SMOTE |
+| `meerax.report` | Self-contained dark-themed HTML model-card report builder |
+| `meerax.logging` | One-call structured logger factory |
+| `meerax.vision` | Image folder dataset loader (PyTorch) + translation-grid plotting (torch or numpy/TF images) |
+
+## Scaffolding Projects
+
+Every project in the ecosystem follows the same PROJECT_STANDARDS.md layout and depends on
+`meerax`. The `meerax` CLI (installed alongside the package) generates or retrofits that layout:
+
+```bash
+# brand-new project
+meerax new my-project --path ~/dev
+
+# retrofit an existing, non-empty directory — additive only, never overwrites
+cd ~/dev/my-existing-notebook-project
+meerax init
+```
+
+`meerax new` creates the full `src/{core,providers,services,utils,data}` + `tests/` + CI
+skeleton, pins `requirements.txt` to the current `meerax` release, and runs `git init`.
+
+`meerax init` fills in whatever's missing from that same layout without touching files that
+already exist, and reports any top-level files it doesn't recognize (e.g. notebooks) so you can
+move them into `src/` by hand.
+
+## Quick Start
+
+```python
+from meerax.llm import ClaudeProvider, PromptTemplate
+from meerax.eval import evaluate_classifier
+from meerax.viz import apply_meerax_theme
+from meerax.report import ReportBuilder, ReportSection
+
+# LLM: swap provider without changing downstream code
+llm = ClaudeProvider()                         # or OpenAIProvider() / OllamaProvider()
+tpl = PromptTemplate("Explain {finding} to a risk manager in 3 sentences.")
+response = llm.generate(tpl.render(finding="high AUC-ROC with low recall"))
+
+# Eval
+metrics = evaluate_classifier(y_true, y_pred, y_prob=probabilities)
+print(metrics)
+# Accuracy : 0.9823
+# F1       : 0.8741
+# AUC-ROC  : 0.9912
+
+# Viz + Report
+apply_meerax_theme()
+rb = ReportBuilder("Fraud Detection — Model Report v0.1.0")
+rb.add_section(ReportSection(
+    title="Performance",
+    metrics=metrics.to_dict(),
+    content=response.content,
+))
+rb.save("reports/model_report.html")
+```
+
+## LLM Provider Interface
+
+All providers implement `LLMProvider.generate()` and `.chat()`. Swap with one line:
+
+```python
+from meerax.llm import ClaudeProvider, OpenAIProvider, OllamaProvider
+
+llm = ClaudeProvider()    # needs ANTHROPIC_API_KEY
+llm = OpenAIProvider()    # needs OPENAI_API_KEY
+llm = OllamaProvider()    # needs Ollama running locally
+```
+
+## Benchmarks
+
+Self-contained benchmark scripts in `benchmarks/`:
+
+| Script | Description |
+|---|---|
+| `kv_cache_benchmark.py` | KV caching simulation at GPT-2 Medium scale |
+
+## Project Structure
+
+```
+the-forge/
+├── meerax/              # Installable package
+│   ├── llm/            # LLM provider abstraction
+│   ├── eval/            # Evaluation metrics
+│   ├── viz/             # Visualization utilities
+│   ├── data/            # Data loading, splitting, resampling
+│   ├── report/          # HTML report builder
+│   ├── scaffold/        # Project skeleton templates + create/retrofit logic
+│   ├── cli.py           # `meerax new` / `meerax init` command entry point
+│   ├── vision/          # Image dataset loader + translation-grid plotting
+│   └── logging.py       # Structured logger
+├── benchmarks/          # Standalone ML benchmark scripts
+├── tests/
+│   └── unit/            # 80 unit tests, zero external deps
+├── LICENSE
+├── pyproject.toml
+├── requirements.txt
+└── VERSION
+```
+
+---
+
+[sameer-portfolio](https://github.com/mauryasameer/sameer-portfolio) · [mauryasameer.com](https://www.mauryasameer.com)

meerax-1.0.0/VERSION

@@ -0,0 +1 @@
+1.0.0

meerax-1.0.0/meerax/__init__.py

@@ -0,0 +1,7 @@
+from importlib.metadata import version
+
+from meerax.logging import setup_logger
+
+__version__ = version("meerax")
+
+__all__ = ["setup_logger", "__version__"]

meerax-1.0.0/meerax/cli.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+import meerax
+from meerax.scaffold.skeleton import create_tree, ensure_meerax_dependency, retrofit_tree
+
+
+def cmd_new(args: argparse.Namespace) -> int:
+    root = Path(args.path) / args.name
+    if root.exists():
+        print(f"error: {root} already exists", file=sys.stderr)
+        return 1
+    result = create_tree(root, args.name)
+    ensure_meerax_dependency(root, meerax.__version__)
+    try:
+        subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
+    except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+        print(f"error: git init failed: {exc}", file=sys.stderr)
+        return 1
+    print(f"created {len(result.created)} files/dirs in {root}")
+    for path in result.created:
+        print(f"  create {path.relative_to(root)}")
+    return 0
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    root = Path(args.path)
+    if not root.exists():
+        print(f"error: {root} does not exist", file=sys.stderr)
+        return 1
+    result = retrofit_tree(root, root.resolve().name)
+    dep_status = ensure_meerax_dependency(root, meerax.__version__)
+    print(f"created {len(result.created)}, skipped {len(result.skipped)} (already present)")
+    for path in result.created:
+        print(f"  create {path.relative_to(root)}")
+    for path in result.skipped:
+        print(f"  skip   {path.relative_to(root)}")
+    print(f"requirements.txt: {dep_status}")
+    if result.unrecognized:
+        print("unrecognized top-level entries (move into src/ manually):")
+        for path in result.unrecognized:
+            print(f"  ? {path.relative_to(root)}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="meerax")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    new_parser = subparsers.add_parser("new", help="scaffold a new project")
+    new_parser.add_argument("name")
+    new_parser.add_argument("--path", default=".")
+    new_parser.set_defaults(func=cmd_new)
+
+    init_parser = subparsers.add_parser("init", help="retrofit an existing project")
+    init_parser.add_argument("--path", default=".")
+    init_parser.set_defaults(func=cmd_init)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

meerax-1.0.0/meerax/data/__init__.py

@@ -0,0 +1,12 @@
+from meerax.data.imbalance import random_undersample, smote_oversample
+from meerax.data.loader import load_csv, load_parquet
+from meerax.data.split import stratified_split, time_split
+
+__all__ = [
+    "load_csv",
+    "load_parquet",
+    "stratified_split",
+    "time_split",
+    "smote_oversample",
+    "random_undersample",
+]

meerax-1.0.0/meerax/data/imbalance.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def smote_oversample(
+    X: np.ndarray,
+    y: np.ndarray,
+    random_state: int = 42,
+) -> tuple[np.ndarray, np.ndarray]:
+    """SMOTE oversampling. Requires imbalanced-learn."""
+    try:
+        from imblearn.over_sampling import SMOTE
+    except ImportError as exc:
+        raise ImportError("Install imbalanced-learn: pip install imbalanced-learn") from exc
+    X_res, y_res = SMOTE(random_state=random_state).fit_resample(X, y)
+    logger.info("SMOTE: %d → %d samples", len(y), len(y_res))
+    return X_res, y_res
+
+
+def random_undersample(
+    X: np.ndarray,
+    y: np.ndarray,
+    random_state: int = 42,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Random majority-class undersampling. Requires imbalanced-learn."""
+    try:
+        from imblearn.under_sampling import RandomUnderSampler
+    except ImportError as exc:
+        raise ImportError("Install imbalanced-learn: pip install imbalanced-learn") from exc
+    X_res, y_res = RandomUnderSampler(random_state=random_state).fit_resample(X, y)
+    logger.info("RandomUnderSampler: %d → %d samples", len(y), len(y_res))
+    return X_res, y_res

meerax-1.0.0/meerax/data/loader.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+def load_csv(
+    path: str | Path,
+    required_columns: list[str] | None = None,
+    dtype: dict | None = None,
+) -> pd.DataFrame:
+    """Load a CSV with optional schema validation.
+
+    Raises:
+        FileNotFoundError: if the file does not exist.
+        ValueError: if required_columns are absent from the file.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Data file not found: {path}")
+    df = pd.read_csv(path, dtype=dtype)
+    logger.info("Loaded %d rows × %d cols from %s", len(df), len(df.columns), path.name)
+    if required_columns:
+        missing = set(required_columns) - set(df.columns)
+        if missing:
+            raise ValueError(f"Missing required columns: {sorted(missing)}")
+    return df
+
+
+def load_parquet(
+    path: str | Path,
+    required_columns: list[str] | None = None,
+) -> pd.DataFrame:
+    """Load a Parquet file with optional schema validation."""
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Data file not found: {path}")
+    df = pd.read_parquet(path)
+    logger.info("Loaded %d rows × %d cols from %s", len(df), len(df.columns), path.name)
+    if required_columns:
+        missing = set(required_columns) - set(df.columns)
+        if missing:
+            raise ValueError(f"Missing required columns: {sorted(missing)}")
+    return df

meerax-1.0.0/meerax/data/split.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import pandas as pd
+
+
+def stratified_split(
+    df: pd.DataFrame,
+    target_col: str,
+    train_ratio: float = 0.7,
+    val_ratio: float = 0.15,
+    random_state: int = 42,
+) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """Stratified train / val / test split preserving class balance."""
+    from sklearn.model_selection import train_test_split
+
+    test_ratio = 1.0 - train_ratio - val_ratio
+    if test_ratio <= 0:
+        raise ValueError("train_ratio + val_ratio must be < 1.0")
+
+    train, temp = train_test_split(
+        df,
+        test_size=val_ratio + test_ratio,
+        stratify=df[target_col],
+        random_state=random_state,
+    )
+    val, test = train_test_split(
+        temp,
+        test_size=test_ratio / (val_ratio + test_ratio),
+        stratify=temp[target_col],
+        random_state=random_state,
+    )
+    return (
+        train.reset_index(drop=True),
+        val.reset_index(drop=True),
+        test.reset_index(drop=True),
+    )
+
+
+def time_split(
+    df: pd.DataFrame,
+    train_ratio: float = 0.8,
+    val_ratio: float = 0.1,
+) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """Chronological train / val / test split — no shuffling."""
+    n = len(df)
+    train_end = int(n * train_ratio)
+    val_end = int(n * (train_ratio + val_ratio))
+    return (
+        df.iloc[:train_end].copy(),
+        df.iloc[train_end:val_end].copy(),
+        df.iloc[val_end:].copy(),
+    )

meerax-1.0.0/meerax/eval/__init__.py

@@ -0,0 +1,13 @@
+from meerax.eval.classification import ClassificationMetrics, evaluate_classifier
+from meerax.eval.text import bleu_score, rouge_l
+from meerax.eval.timeseries import TimeSeriesMetrics, adf_stationarity, evaluate_forecast
+
+__all__ = [
+    "ClassificationMetrics",
+    "evaluate_classifier",
+    "TimeSeriesMetrics",
+    "evaluate_forecast",
+    "adf_stationarity",
+    "bleu_score",
+    "rouge_l",
+]

meerax-1.0.0/meerax/eval/classification.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class ClassificationMetrics:
+    accuracy: float
+    precision: float
+    recall: float
+    f1: float
+    auc_roc: float | None
+    support: int
+
+    def __str__(self) -> str:
+        lines = [
+            f"Accuracy : {self.accuracy:.4f}",
+            f"Precision: {self.precision:.4f}",
+            f"Recall   : {self.recall:.4f}",
+            f"F1       : {self.f1:.4f}",
+        ]
+        if self.auc_roc is not None:
+            lines.append(f"AUC-ROC  : {self.auc_roc:.4f}")
+        lines.append(f"Support  : {self.support}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, float | int | None]:
+        return {
+            "accuracy": self.accuracy,
+            "precision": self.precision,
+            "recall": self.recall,
+            "f1": self.f1,
+            "auc_roc": self.auc_roc,
+            "support": self.support,
+        }
+
+
+def evaluate_classifier(
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+    y_prob: np.ndarray | None = None,
+    average: str = "binary",
+) -> ClassificationMetrics:
+    """Compute a standard classification metric bundle.
+
+    Args:
+        y_true:  Ground-truth labels.
+        y_pred:  Hard predictions.
+        y_prob:  Probability estimates for AUC-ROC (1-D for binary, 2-D for multiclass).
+        average: Averaging strategy passed to sklearn ('binary', 'macro', 'weighted').
+    """
+    from sklearn.metrics import (
+        accuracy_score,
+        f1_score,
+        precision_score,
+        recall_score,
+        roc_auc_score,
+    )
+
+    auc: float | None = None
+    if y_prob is not None:
+        try:
+            prob = y_prob if y_prob.ndim == 1 else y_prob[:, 1]
+            auc = float(roc_auc_score(y_true, prob))
+        except ValueError:
+            pass
+
+    return ClassificationMetrics(
+        accuracy=float(accuracy_score(y_true, y_pred)),
+        precision=float(precision_score(y_true, y_pred, average=average, zero_division=0)),
+        recall=float(recall_score(y_true, y_pred, average=average, zero_division=0)),
+        f1=float(f1_score(y_true, y_pred, average=average, zero_division=0)),
+        auc_roc=auc,
+        support=int(len(y_true)),
+    )