genderfluid-tiny 1.0.0__py3-none-any.whl

genderfluid/__init__.py

@@ -0,0 +1,78 @@
+"""genderfluid-tiny: Ultra-tiny name-gender association classifier."""
+
+from genderfluid.inference import (
+    predict_name,
+    predict_names,
+    GenderfluidModel,
+)
+
+
+def classify_name(name: str) -> str:
+    """
+    Return just the classification string.
+
+    Returns one of: "girl-associated", "boy-associated", "uncertain"
+
+    Example::
+
+        from genderfluid import classify_name
+
+        classify_name("Emma")    # "girl-associated"
+        classify_name("James")   # "boy-associated"
+        classify_name("Alex")    # "uncertain"
+    """
+    return predict_name(name)["classification"]
+
+
+def is_girl_name(name: str) -> bool:
+    """
+    Return True if the name is classified as girl-associated.
+
+    Example::
+
+        from genderfluid import is_girl_name
+
+        if is_girl_name("Emma"):
+            print("girl name")
+    """
+    return predict_name(name)["classification"] == "girl-associated"
+
+
+def is_boy_name(name: str) -> bool:
+    """
+    Return True if the name is classified as boy-associated.
+
+    Example::
+
+        from genderfluid import is_boy_name
+
+        if is_boy_name("James"):
+            print("boy name")
+    """
+    return predict_name(name)["classification"] == "boy-associated"
+
+
+def name_probability(name: str) -> float:
+    """
+    Return the girl-associated probability as a float between 0 and 1.
+
+    Example::
+
+        from genderfluid import name_probability
+
+        p = name_probability("Emma")  # 0.97
+        p = name_probability("Alex")  # 0.27
+    """
+    return predict_name(name)["girl_associated_probability"]
+
+
+__version__ = "1.0.0"
+__all__ = [
+    "predict_name",
+    "predict_names",
+    "GenderfluidModel",
+    "classify_name",
+    "is_girl_name",
+    "is_boy_name",
+    "name_probability",
+]

genderfluid/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as: python -m genderfluid"""
+
+from genderfluid.cli import main
+
+if __name__ == "__main__":
+    main()

genderfluid/calibration.py

@@ -0,0 +1,110 @@
+"""Probability calibration analysis."""
+
+import numpy as np
+
+
+def calibration_error(
+    y_true: np.ndarray,
+    y_proba: np.ndarray,
+    n_bins: int = 10,
+) -> float:
+    """
+    Compute Expected Calibration Error (ECE).
+
+    Args:
+        y_true: True class labels
+        y_proba: Predicted probabilities
+        n_bins: Number of bins for calibration
+
+    Returns:
+        Expected calibration error
+    """
+    bin_boundaries = np.linspace(0, 1, n_bins + 1)
+    ece = 0.0
+
+    for i in range(n_bins):
+        lower = bin_boundaries[i]
+        upper = bin_boundaries[i + 1]
+
+        # Find samples in this probability bin
+        mask = (y_proba.max(axis=1) >= lower) & (y_proba.max(axis=1) < upper)
+        if mask.sum() == 0:
+            continue
+
+        bin_proba = y_proba[mask].max(axis=1)
+        bin_true = y_true[mask] == np.argmax(y_proba[mask], axis=1)
+
+        avg_confidence = bin_proba.mean()
+        avg_accuracy = bin_true.mean()
+
+        ece += mask.sum() / len(y_true) * abs(avg_accuracy - avg_confidence)
+
+    return float(ece)
+
+
+def reliability_data(
+    y_true: np.ndarray,
+    y_proba: np.ndarray,
+    n_bins: int = 10,
+) -> list[dict]:
+    """
+    Compute reliability diagram data.
+
+    Returns list of dicts with bin_lower, bin_upper, avg_confidence, avg_accuracy, count.
+    """
+    bin_boundaries = np.linspace(0, 1, n_bins + 1)
+    result = []
+
+    for i in range(n_bins):
+        lower = bin_boundaries[i]
+        upper = bin_boundaries[i + 1]
+
+        mask = (y_proba.max(axis=1) >= lower) & (y_proba.max(axis=1) < upper)
+        if mask.sum() == 0:
+            result.append({
+                "bin_lower": float(lower),
+                "bin_upper": float(upper),
+                "avg_confidence": float((lower + upper) / 2),
+                "avg_accuracy": 0.0,
+                "count": 0,
+            })
+            continue
+
+        bin_proba = y_proba[mask].max(axis=1)
+        bin_true = (y_true[mask] == np.argmax(y_proba[mask], axis=1)).astype(float)
+
+        result.append({
+            "bin_lower": float(lower),
+            "bin_upper": float(upper),
+            "avg_confidence": float(bin_proba.mean()),
+            "avg_accuracy": float(bin_true.mean()),
+            "count": int(mask.sum()),
+        })
+
+    return result
+
+
+def confusion_matrix(
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+    labels: list[str],
+) -> dict:
+    """
+    Compute confusion matrix as a dict.
+
+    Returns:
+        {label: {predicted_label: count}}
+    """
+    n_labels = len(labels)
+    matrix = np.zeros((n_labels, n_labels), dtype=int)
+
+    for true, pred in zip(y_true, y_pred):
+        matrix[true, pred] += 1
+
+    result = {}
+    for i, true_label in enumerate(labels):
+        result[true_label] = {}
+        for j, pred_label in enumerate(labels):
+            result[true_label][pred_label] = int(matrix[i, j])
+
+    return result

genderfluid/classifier.py

@@ -0,0 +1,181 @@
+"""Logistic regression classifier with lightweight probability calibration."""
+
+import numpy as np
+from sklearn.linear_model import LogisticRegression
+from typing import Optional
+
+
+LABELS = ["girl-associated", "boy-associated", "uncertain"]
+LABEL_TO_IDX = {label: i for i, label in enumerate(LABELS)}
+NUM_CLASSES = 3
+MIN_EXAMPLES_PER_CLASS = 5
+
+
+def _sigmoid(x):
+    return 1.0 / (1.0 + np.exp(-np.clip(x, -30, 30)))
+
+
+class NameClassifier:
+    """
+    Logistic regression classifier for name-gender association.
+
+    Uses lightweight sigmoid (Platt) calibration instead of
+    CalibratedClassifierCV to keep memory usage minimal.
+    """
+
+    def __init__(
+        self,
+        C: float = 1.0,
+        max_iter: int = 1000,
+        min_confidence: float = 0.70,
+    ):
+        self.C = C
+        self.max_iter = max_iter
+        self.min_confidence = min_confidence
+        self.model: Optional[LogisticRegression] = None
+        # Per-class sigmoid calibration parameters: A, B for sigmoid(A*raw + B)
+        self.calib_A: Optional[np.ndarray] = None
+        self.calib_B: Optional[np.ndarray] = None
+
+    def train(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        sample_weight: Optional[np.ndarray] = None,
+    ) -> None:
+        """Train the classifier with all 3 classes guaranteed."""
+        rng = np.random.RandomState(42)
+        unique_classes = set(y.tolist())
+        missing = set(range(NUM_CLASSES)) - unique_classes
+
+        X_train = X
+        y_train = y.copy()
+        sw_train = sample_weight.copy() if sample_weight is not None else None
+
+        for cls in sorted(missing):
+            n_pad = MIN_EXAMPLES_PER_CLASS
+            X_pad = rng.randn(n_pad, X.shape[1]).astype(np.float32) * 0.001
+            y_pad = np.full(n_pad, cls, dtype=int)
+            X_train = np.vstack([X_train, X_pad])
+            y_train = np.concatenate([y_train, y_pad])
+            if sw_train is not None:
+                w_pad = np.full(n_pad, 0.001)
+                sw_train = np.concatenate([sw_train, w_pad])
+            else:
+                sw_train = np.concatenate([
+                    np.ones(len(y), dtype=np.float32),
+                    np.full(n_pad, 0.001, dtype=np.float32),
+                ])
+
+        self.model = LogisticRegression(
+            C=self.C,
+            max_iter=self.max_iter,
+            solver="lbfgs",
+            random_state=42,
+        )
+        self.model.fit(X_train, y_train, sample_weight=sw_train)
+
+        # Lightweight Platt scaling calibration on a holdout from training data
+        n = len(y_train)
+        cal_size = min(2000, n // 5)
+        idx = rng.choice(n, cal_size, replace=False)
+        X_cal, y_cal = X_train[idx], y_train[idx]
+
+        raw_proba = self.model.predict_proba(X_cal)
+        # Fit per-class sigmoid: P(y=c|raw) = sigmoid(A * logit(raw) + B)
+        self.calib_A = np.ones(NUM_CLASSES, dtype=np.float32)
+        self.calib_B = np.zeros(NUM_CLASSES, dtype=np.float32)
+
+        for c in range(NUM_CLASSES):
+            targets = (y_cal == c).astype(np.float32)
+            if targets.sum() < 5 or (1 - targets).sum() < 5:
+                continue
+            raw = raw_proba[:, c].clip(1e-7, 1 - 1e-7)
+            logit = np.log(raw / (1 - raw))
+            # Simple linear fit: A, B via least squares
+            # Platt scaling: minimize targets * log(sigmoid(A*l+B)) + (1-targets) * log(1-sigmoid(A*l+B))
+            # Use a robust 2-parameter fit
+            best_A, best_B = 1.0, 0.0
+            best_loss = float("inf")
+            for A_try in [0.5, 1.0, 1.5, 2.0]:
+                for B_try in [-1.0, -0.5, 0.0, 0.5, 1.0]:
+                    s = _sigmoid(A_try * logit + B_try)
+                    s = s.clip(1e-7, 1 - 1e-7)
+                    loss = -np.mean(targets * np.log(s) + (1 - targets) * np.log(1 - s))
+                    if loss < best_loss:
+                        best_loss = loss
+                        best_A, best_B = A_try, B_try
+            self.calib_A[c] = best_A
+            self.calib_B[c] = best_B
+
+        del X_cal, y_cal, raw_proba
+        import gc
+        gc.collect()
+
+    def _calibrate_proba(self, raw_proba: np.ndarray) -> np.ndarray:
+        """Apply sigmoid calibration to raw probabilities."""
+        if self.calib_A is None:
+            return raw_proba
+
+        calibrated = np.zeros_like(raw_proba)
+        for c in range(raw_proba.shape[1]):
+            raw = raw_proba[:, c].clip(1e-7, 1 - 1e-7)
+            logit = np.log(raw / (1 - raw))
+            calibrated[:, c] = _sigmoid(self.calib_A[c] * logit + self.calib_B[c])
+
+        # Renormalize
+        row_sums = calibrated.sum(axis=1, keepdims=True)
+        row_sums = np.maximum(row_sums, 1e-10)
+        calibrated /= row_sums
+        return calibrated
+
+    def predict_proba(self, X: np.ndarray) -> np.ndarray:
+        """Get calibrated probabilities. Always returns shape (n, 3)."""
+        if self.model is None:
+            raise RuntimeError("Model not trained. Call train() first.")
+
+        raw_proba = self.model.predict_proba(X)
+
+        # Ensure 3-column output
+        if raw_proba.shape[1] < NUM_CLASSES:
+            full = np.zeros((raw_proba.shape[0], NUM_CLASSES), dtype=np.float32)
+            for i, c in enumerate(self.model.classes_):
+                full[:, c] = raw_proba[:, i]
+            for c in range(NUM_CLASSES):
+                if c not in self.model.classes_:
+                    full[:, c] = 1.0 / NUM_CLASSES
+            row_sums = full.sum(axis=1, keepdims=True)
+            full /= np.maximum(row_sums, 1e-10)
+            raw_proba = full
+
+        return self._calibrate_proba(raw_proba.astype(np.float32))
+
+    def predict(self, X: np.ndarray) -> tuple:
+        """
+        Predict class and probabilities.
+        Returns (class_indices, probabilities) where probabilities shape is (n_samples, 3)
+        """
+        proba = self.predict_proba(X)
+
+        max_proba = np.max(proba, axis=1)
+        below_threshold = max_proba < self.min_confidence
+
+        class_indices = np.argmax(proba, axis=1)
+        class_indices[below_threshold] = LABEL_TO_IDX["uncertain"]
+
+        return class_indices, proba
+
+    def get_config(self) -> dict:
+        return {
+            "C": self.C,
+            "max_iter": self.max_iter,
+            "min_confidence": self.min_confidence,
+        }
+
+    @classmethod
+    def from_config(cls, config: dict) -> "NameClassifier":
+        return cls(
+            C=config.get("C", 1.0),
+            max_iter=config.get("max_iter", 1000),
+            min_confidence=config.get("min_confidence", 0.70),
+        )

genderfluid/cli.py

@@ -0,0 +1,270 @@
+"""Full-featured CLI for genderfluid-tiny."""
+
+import argparse
+import json
+import sys
+import os
+import time
+
+SUBCOMMANDS = {"predict", "stats", "benchmark", "interactive"}
+
+
+def _load_model(model_path=None):
+    from genderfluid import GenderfluidModel
+    return GenderfluidModel(model_path)
+
+
+def format_result(result: dict, color: bool = False) -> str:
+    lines = [f"Name: {result['name']}", ""]
+
+    girl = result["girl_associated_probability"] * 100
+    boy = result["boy_associated_probability"] * 100
+    unc = result["uncertain_probability"] * 100
+
+    if color:
+        lines.append(f"Girl-associated: \033[35m{girl:.1f}%\033[0m")
+        lines.append(f"Boy-associated:  \033[34m{boy:.1f}%\033[0m")
+        lines.append(f"Uncertain:       {unc:.1f}%")
+    else:
+        lines.append(f"Girl-associated: {girl:.1f}%")
+        lines.append(f"Boy-associated:  {boy:.1f}%")
+        lines.append(f"Uncertain:       {unc:.1f}%")
+
+    lines.append("")
+    lines.append(f"Classification: {result['classification']}")
+    lines.append(f"Confidence:     {result['confidence']}")
+
+    if "warning" in result:
+        lines.append(f"Warning: {result['warning']}")
+    if "context_warning" in result:
+        lines.append(f"Note: {result['context_warning']}")
+    return "\n".join(lines)
+
+
+def format_compare(results: list[dict]) -> str:
+    lines = [
+        f"{'Name':<25} {'Classification':<20} {'Girl':>6} {'Boy':>6} {'Confidence':<10}",
+        "-" * 70,
+    ]
+    for r in results:
+        g = f"{r['girl_associated_probability']*100:.0f}%"
+        b = f"{r['boy_associated_probability']*100:.0f}%"
+        lines.append(f"{r['name']:<25} {r['classification']:<20} {g:>6} {b:>6} {r['confidence']:<10}")
+    return "\n".join(lines)
+
+
+def interactive_mode(model=None, color: bool = False):
+    print("Name Gender Association Predictor")
+    print("Type 'quit' to exit.\n")
+
+    while True:
+        try:
+            name = input("Name > ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+
+        if not name or name.lower() in ("quit", "exit", "q"):
+            break
+
+        try:
+            t0 = time.time()
+            if model:
+                result = model.predict(name)
+            else:
+                from genderfluid import predict_name
+                result = predict_name(name)
+            elapsed = (time.time() - t0) * 1000
+            print()
+            print(format_result(result, color=color))
+            print(f"  ({elapsed:.1f} ms)")
+            print()
+        except FileNotFoundError as e:
+            print(f"Error: {e}")
+            break
+        except Exception as e:
+            print(f"Error: {e}")
+
+
+def cmd_predict(args):
+    model = _load_model(args.model)
+
+    if args.file:
+        with open(args.file, "r", encoding="utf-8") as f:
+            names = [line.strip() for line in f if line.strip()]
+
+        t0 = time.time()
+        results = model.predict_batch(names)
+        elapsed = time.time() - t0
+
+        if args.json:
+            for r in results:
+                print(json.dumps(r, ensure_ascii=False))
+        else:
+            print(format_compare(results))
+
+        print(f"\n{len(names)} names in {elapsed*1000:.1f} ms ({len(names)/elapsed:.0f} names/sec)")
+        return
+
+    if args.compare:
+        names = [n.strip() for n in args.compare if n.strip()]
+        if not names:
+            print("Error: no names provided")
+            return
+
+        t0 = time.time()
+        results = model.predict_batch(names)
+        elapsed = time.time() - t0
+
+        if args.json:
+            print(json.dumps(results, ensure_ascii=False, indent=2))
+        else:
+            print(format_compare(results))
+            print(f"\n{len(names)} names in {elapsed*1000:.1f} ms")
+        return
+
+    if args.name:
+        t0 = time.time()
+        result = model.predict(args.name)
+        elapsed = (time.time() - t0) * 1000
+
+        if args.json:
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        else:
+            print(format_result(result, color=args.color))
+            if args.verbose:
+                print(f"\n  Latency: {elapsed:.1f} ms")
+        return
+
+    print("Usage: genderfluid predict <name> [options]")
+    print("       genderfluid predict --compare <name1> <name2> ...")
+    print("       genderfluid predict --file names.txt")
+
+
+def cmd_stats(args):
+    model = _load_model(args.model)
+    meta = model.metadata
+    size = os.path.getsize(model.model_path)
+
+    print("Model Statistics")
+    print("=" * 40)
+    print(f"  Model:      genderfluid-tiny")
+    print(f"  Version:    {meta.get('version', 'unknown')}")
+    print(f"  Size:       {size / (1024*1024):.2f} MB ({size:,} bytes)")
+    if "feature_dimensions" in meta:
+        print(f"  Features:   {meta['feature_dimensions']}")
+    if "data_source" in meta:
+        print(f"  Data:       {meta['data_source']}")
+    if "train_size" in meta:
+        print(f"  Train:      {meta['train_size']:,}")
+    if "val_size" in meta:
+        print(f"  Validation: {meta['val_size']:,}")
+    if "test_size" in meta:
+        print(f"  Test:       {meta['test_size']:,}")
+    if "test_f1" in meta:
+        print(f"  Test F1:    {meta['test_f1']:.3f}")
+    if "validation_f1" in meta:
+        print(f"  Val F1:     {meta['validation_f1']:.3f}")
+    print(f"  Classes:    girl-associated, boy-associated, uncertain")
+
+
+def cmd_benchmark(args):
+    from genderfluid import GenderfluidModel
+
+    print("Benchmark")
+    print("=" * 40)
+
+    t0 = time.time()
+    model = GenderfluidModel(args.model)
+    load_time = (time.time() - t0) * 1000
+    size = os.path.getsize(model.model_path)
+    print(f"  Model size:     {size / (1024*1024):.2f} MB")
+    print(f"  Loading time:   {load_time:.1f} ms")
+
+    test_names = ["Emma", "James", "Alex", "Michelle Renatta Chan", "Max", "Taylor",
+                  "Elva Retta", "Sam", "Jordan", "Chris"]
+
+    # Single name
+    times = []
+    for _ in range(10):
+        for name in test_names:
+            t0 = time.time()
+            model.predict(name)
+            times.append((time.time() - t0) * 1000)
+    avg_single = sum(times) / len(times)
+    print(f"  Single name:    {avg_single:.2f} ms")
+
+    # Batch
+    for batch_size in [10, 100, 1000]:
+        batch = (test_names * (batch_size // len(test_names) + 1))[:batch_size]
+        t0 = time.time()
+        model.predict_batch(batch)
+        elapsed = (time.time() - t0) * 1000
+        throughput = batch_size / (elapsed / 1000)
+        print(f"  Batch {batch_size:>4}:     {elapsed:>7.1f} ms  ({throughput:,.0f} names/sec)")
+
+    try:
+        import resource
+        mem = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024
+        print(f"  Peak RSS:       {mem:.0f} MB")
+    except (ImportError, AttributeError):
+        pass
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="genderfluid",
+        description="genderfluid-tiny: name gender association classifier",
+    )
+    parser.add_argument("--version", action="version", version="genderfluid-tiny 1.0.0")
+    parser.add_argument("--color", action="store_true", help="colored output")
+    parser.add_argument("--verbose", "-v", action="store_true", help="verbose output")
+
+    sub = parser.add_subparsers(dest="command")
+
+    p_predict = sub.add_parser("predict", help="predict gender association for a name")
+    p_predict.add_argument("name", nargs="?", help="name to classify")
+    p_predict.add_argument("--file", "-f", help="file with one name per line")
+    p_predict.add_argument("--compare", "-c", nargs="+", help="compare multiple names")
+    p_predict.add_argument("--json", "-j", action="store_true", help="output JSON")
+    p_predict.add_argument("--model", "-m", help="path to model file")
+
+    p_stats = sub.add_parser("stats", help="show model statistics")
+    p_stats.add_argument("--model", "-m", help="path to model file")
+
+    p_bench = sub.add_parser("benchmark", help="run inference benchmark")
+    p_bench.add_argument("--model", "-m", help="path to model file")
+
+    p_inter = sub.add_parser("interactive", help="interactive prediction mode")
+    p_inter.add_argument("--model", "-m", help="path to model file")
+
+    return parser
+
+
+def main():
+    parser = _build_parser()
+
+    # Detect backward-compatible calling: predict.py "Elva Retta"
+    # sys.argv[0] ends with predict.py and argv[1] is not a subcommand or flag
+    if len(sys.argv) > 1:
+        first = sys.argv[1]
+        if first not in SUBCOMMANDS and not first.startswith("-") and first != "--help":
+            # Looks like a bare name -- treat as: predict <name>
+            sys.argv = [sys.argv[0], "predict"] + sys.argv[1:]
+
+    args = parser.parse_args()
+
+    if args.command == "predict":
+        cmd_predict(args)
+    elif args.command == "stats":
+        cmd_stats(args)
+    elif args.command == "benchmark":
+        cmd_benchmark(args)
+    elif args.command == "interactive":
+        interactive_mode(_load_model(getattr(args, 'model', None)))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()