featrix-modelcard 1.10__tar.gz

featrix_modelcard-1.10/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include featrix_modelcard *.py
+

featrix_modelcard-1.10/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: featrix-modelcard
+Version: 1.10
+Summary: Render Featrix Sphere Model Card JSON to HTML or plain text
+Home-page: https://github.com/featrix/model-card
+Author: Featrix
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# Featrix Model Card - Python Package
+
+Python package for rendering Featrix Model Card JSON to HTML or plain text.
+
+**HTML rendering** delegates to the canonical JavaScript renderer loaded from CDN,
+ensuring the Python output always matches the JS version.
+
+**Text rendering** is a standalone Python implementation for terminal/log output.
+
+## Installation
+
+```bash
+pip install featrix-modelcard
+```
+
+## Usage
+
+### HTML Renderer
+
+The HTML renderer generates a standalone page that loads `model-card.js` from the
+Featrix CDN. The JavaScript renderer handles all layout, styling, and interactivity.
+
+```python
+from featrix_modelcard import render_html, render_html_to_file
+
+# Load model card JSON
+import json
+with open('model_card.json', 'r') as f:
+    model_card = json.load(f)
+
+# Render to file
+render_html_to_file(model_card, 'output.html')
+
+# Render to string
+html = render_html(model_card)
+
+# With 3D sphere visualization
+html = render_html(model_card, show_sphere=True)
+
+# With explicit session ID for sphere
+html = render_html(model_card, show_sphere=True, session_id='my-session-id')
+
+# Override CDN URL (e.g. for local development)
+html = render_html(model_card, cdn_url='http://localhost:8080/model-card.js')
+```
+
+### Text Renderer
+
+```python
+from featrix_modelcard import render_brief_text, render_detailed_text, print_text
+
+# Brief summary
+print_text(model_card, detailed=False)
+
+# Detailed output
+print_text(model_card, detailed=True)
+
+# Get as strings
+brief = render_brief_text(model_card)
+detailed = render_detailed_text(model_card)
+```
+
+## API Reference
+
+### HTML Functions
+
+- `render_html(model_card_json, *, show_sphere=False, session_id=None, cdn_url=None)` -> `str`
+- `render_html_to_file(model_card_json, output_path, *, show_sphere=False, session_id=None, cdn_url=None)` -> `str`
+- `print_html(model_card_json, file=None, **kwargs)` -> `str`
+
+### Text Functions
+
+- `render_brief_text(model_card_json)` -> `str`
+- `render_detailed_text(model_card_json)` -> `str`
+- `render_text_to_file(model_card_json, output_path, detailed=True)` -> `str`
+- `print_text(model_card_json, detailed=True, file=None)` -> `str`
+
+## Architecture
+
+The HTML renderer is a thin wrapper that embeds your model card JSON into a page
+that loads the canonical `FeatrixModelCard` JavaScript renderer from the CDN.
+This means:
+
+- Python HTML output is always in sync with the JS version
+- No rendering logic to maintain in Python
+- All styling, interactivity, and features come from the JS renderer
+- Zero external Python dependencies
+
+The text renderer is a standalone Python implementation for use in terminals,
+logs, and non-browser contexts.

featrix_modelcard-1.10/README.md

@@ -0,0 +1,90 @@
+# Featrix Model Card - Python Package
+
+Python package for rendering Featrix Model Card JSON to HTML or plain text.
+
+**HTML rendering** delegates to the canonical JavaScript renderer loaded from CDN,
+ensuring the Python output always matches the JS version.
+
+**Text rendering** is a standalone Python implementation for terminal/log output.
+
+## Installation
+
+```bash
+pip install featrix-modelcard
+```
+
+## Usage
+
+### HTML Renderer
+
+The HTML renderer generates a standalone page that loads `model-card.js` from the
+Featrix CDN. The JavaScript renderer handles all layout, styling, and interactivity.
+
+```python
+from featrix_modelcard import render_html, render_html_to_file
+
+# Load model card JSON
+import json
+with open('model_card.json', 'r') as f:
+    model_card = json.load(f)
+
+# Render to file
+render_html_to_file(model_card, 'output.html')
+
+# Render to string
+html = render_html(model_card)
+
+# With 3D sphere visualization
+html = render_html(model_card, show_sphere=True)
+
+# With explicit session ID for sphere
+html = render_html(model_card, show_sphere=True, session_id='my-session-id')
+
+# Override CDN URL (e.g. for local development)
+html = render_html(model_card, cdn_url='http://localhost:8080/model-card.js')
+```
+
+### Text Renderer
+
+```python
+from featrix_modelcard import render_brief_text, render_detailed_text, print_text
+
+# Brief summary
+print_text(model_card, detailed=False)
+
+# Detailed output
+print_text(model_card, detailed=True)
+
+# Get as strings
+brief = render_brief_text(model_card)
+detailed = render_detailed_text(model_card)
+```
+
+## API Reference
+
+### HTML Functions
+
+- `render_html(model_card_json, *, show_sphere=False, session_id=None, cdn_url=None)` -> `str`
+- `render_html_to_file(model_card_json, output_path, *, show_sphere=False, session_id=None, cdn_url=None)` -> `str`
+- `print_html(model_card_json, file=None, **kwargs)` -> `str`
+
+### Text Functions
+
+- `render_brief_text(model_card_json)` -> `str`
+- `render_detailed_text(model_card_json)` -> `str`
+- `render_text_to_file(model_card_json, output_path, detailed=True)` -> `str`
+- `print_text(model_card_json, detailed=True, file=None)` -> `str`
+
+## Architecture
+
+The HTML renderer is a thin wrapper that embeds your model card JSON into a page
+that loads the canonical `FeatrixModelCard` JavaScript renderer from the CDN.
+This means:
+
+- Python HTML output is always in sync with the JS version
+- No rendering logic to maintain in Python
+- All styling, interactivity, and features come from the JS renderer
+- Zero external Python dependencies
+
+The text renderer is a standalone Python implementation for use in terminals,
+logs, and non-browser contexts.

featrix_modelcard-1.10/featrix_modelcard/__init__.py

@@ -0,0 +1,67 @@
+"""
+Featrix Model Card - Python Package
+
+Render Featrix Model Card JSON to HTML or plain text.
+
+HTML rendering delegates to the canonical JavaScript renderer (loaded from CDN),
+ensuring the Python output always matches the JS version.
+
+Text rendering is a standalone Python implementation for terminal/log output.
+"""
+
+from .html_renderer import render_html, render_to_file as render_html_to_file
+from .text_renderer import (
+    render_brief_text,
+    render_detailed_text,
+    render_to_file as render_text_to_file,
+)
+
+__version__ = "1.10"
+
+
+def print_html(model_card_json, file=None, **kwargs):
+    """
+    Render model card to HTML and print it.
+
+    Args:
+        model_card_json: Model card JSON dictionary.
+        file: File-like object to print to (default: sys.stdout).
+        **kwargs: Passed to render_html (show_sphere, session_id, cdn_url).
+
+    Returns:
+        str: The rendered HTML string.
+    """
+    html = render_html(model_card_json, **kwargs)
+    print(html, file=file)
+    return html
+
+
+def print_text(model_card_json, detailed=True, file=None):
+    """
+    Render model card to text and print it.
+
+    Args:
+        model_card_json: Model card JSON dictionary.
+        detailed: If True, render detailed version; if False, render brief version.
+        file: File-like object to print to (default: sys.stdout).
+
+    Returns:
+        str: The rendered text string.
+    """
+    if detailed:
+        text = render_detailed_text(model_card_json)
+    else:
+        text = render_brief_text(model_card_json)
+    print(text, file=file)
+    return text
+
+
+__all__ = [
+    "render_html",
+    "render_html_to_file",
+    "render_brief_text",
+    "render_detailed_text",
+    "render_text_to_file",
+    "print_html",
+    "print_text",
+]

featrix_modelcard-1.10/featrix_modelcard/html_renderer.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""
+HTML renderer for Featrix Model Card JSON.
+
+Generates a standalone HTML page that loads the canonical JavaScript renderer
+from the CDN, ensuring the Python output always matches the JS version.
+"""
+
+import json
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+CDN_BASE = "https://bits.featrix.com/js/featrix-modelcard"
+
+
+def render_html(
+    model_card_json: Dict[str, Any],
+    *,
+    show_sphere: bool = False,
+    session_id: Optional[str] = None,
+    cdn_url: Optional[str] = None,
+) -> str:
+    """
+    Render a model card JSON dict to a standalone HTML page.
+
+    Uses the canonical FeatrixModelCard JavaScript renderer loaded from CDN,
+    so the output is always in sync with the JS version.
+
+    Args:
+        model_card_json: Model card JSON dictionary.
+        show_sphere: If True, enable the 3D sphere visualization thumbnail.
+        session_id: Explicit session ID for the sphere viewer. If not provided,
+                    it will be resolved from the model card data.
+        cdn_url: Override the CDN URL for model-card.js.
+
+    Returns:
+        str: Complete standalone HTML document.
+    """
+    js_url = cdn_url or f"{CDN_BASE}/model-card.js"
+    model_name = (model_card_json.get("model_identification") or {}).get(
+        "name", "Model Card"
+    )
+
+    # Build the options object for renderHTML
+    options_parts = []
+    if show_sphere:
+        options_parts.append("showSphere: true")
+    if session_id:
+        options_parts.append(f'sessionId: {json.dumps(session_id)}')
+    options_js = "{" + ", ".join(options_parts) + "}" if options_parts else "{}"
+
+    json_str = json.dumps(model_card_json, indent=2)
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Model Card - {_escape_html(model_name)}</title>
+    <style>
+        body {{
+            margin: 0;
+            padding: 20px;
+            background: #fff;
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        }}
+    </style>
+</head>
+<body>
+    <div id="model-card-container"></div>
+    <script src="{_escape_html(js_url)}"></script>
+    <script>
+        var modelCardJson = {json_str};
+        var options = {options_js};
+        var container = document.getElementById('model-card-container');
+        container.innerHTML = FeatrixModelCard.renderHTML(modelCardJson, options);
+        FeatrixModelCard.attachEventListeners(container);
+    </script>
+</body>
+</html>"""
+
+
+def render_to_file(
+    model_card_json: Dict[str, Any],
+    output_path: str,
+    *,
+    show_sphere: bool = False,
+    session_id: Optional[str] = None,
+    cdn_url: Optional[str] = None,
+) -> str:
+    """
+    Render model card JSON to an HTML file.
+
+    Args:
+        model_card_json: Model card JSON dictionary.
+        output_path: Path to write the HTML file.
+        show_sphere: If True, enable the 3D sphere visualization.
+        session_id: Explicit session ID for the sphere viewer.
+        cdn_url: Override the CDN URL for model-card.js.
+
+    Returns:
+        str: The output_path that was written to.
+    """
+    html = render_html(
+        model_card_json,
+        show_sphere=show_sphere,
+        session_id=session_id,
+        cdn_url=cdn_url,
+    )
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(html)
+    return output_path
+
+
+def _escape_html(text: str) -> str:
+    """Escape HTML special characters."""
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )

featrix_modelcard-1.10/featrix_modelcard/text_renderer.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+"""
+Plain text renderer for Featrix Model Card JSON.
+
+Provides both brief and detailed versions matching the current JSON schema
+(model_identification, embedding_space, best_epochs, class_imbalance,
+training_optimization, training_dataset, disk_usage).
+"""
+
+import json
+import re
+from typing import Any, Dict, Optional
+
+
+def format_value(value: Any, precision: int = 4) -> str:
+    """Format a value for display."""
+    if value is None:
+        return "N/A"
+    if isinstance(value, float):
+        return f"{value:.{precision}f}".rstrip("0").rstrip(".")
+    if isinstance(value, bool):
+        return str(value)
+    if isinstance(value, (list, dict)):
+        return json.dumps(value, indent=2)
+    return str(value)
+
+
+def format_pct(value: Optional[float]) -> str:
+    """Format a 0-1 float as a percentage."""
+    if value is None:
+        return "N/A"
+    return f"{value * 100:.1f}%"
+
+
+def format_large_number(value) -> str:
+    """Format large numbers (e.g. 264925317 -> 265.0M)."""
+    if value is None:
+        return "N/A"
+    if value >= 1_000_000_000:
+        return f"{value / 1_000_000_000:.1f}B"
+    if value >= 1_000_000:
+        return f"{value / 1_000_000:.1f}M"
+    if value >= 1_000:
+        return f"{value / 1_000:.1f}K"
+    return f"{value:,}"
+
+
+def _map_model_type(mi: dict) -> str:
+    """Map model_type + target_column_type to display string."""
+    model_type = mi.get("model_type", "")
+    target_type = (mi.get("target_column_type") or "").lower()
+    mt = model_type.lower()
+
+    if mt in ("embedding space", "es"):
+        return "Foundational Embedding Space"
+    if mt in ("single predictor", "sp"):
+        if target_type == "set":
+            return "Binary Classifier"
+        if target_type == "scalar":
+            return "Regression"
+        return "Single Predictor"
+    return model_type or "N/A"
+
+
+def _parse_model_path(path: Optional[str]) -> tuple:
+    """Extract session ID and job ID from best_model_path."""
+    if not path:
+        return None, None
+    parts = path.split("/")
+    session_id = None
+    job_id = None
+    for part in parts:
+        if part.startswith("predictor-"):
+            session_id = part[: len(part) - 37] if len(part) > 37 else part
+        if part.startswith("train_single_predictor_") or part.startswith("train_"):
+            job_id = part
+    return session_id, job_id
+
+
+# ---------------------------------------------------------------------------
+# Brief renderer
+# ---------------------------------------------------------------------------
+
+
+def render_brief_text(data: Dict[str, Any]) -> str:
+    """Render a compact one-screen summary of the model card."""
+    mi = data.get("model_identification", {})
+    be = data.get("best_epochs", {})
+    ci = data.get("class_imbalance", {})
+    es = data.get("embedding_space", {})
+
+    model_name = mi.get("name", "Model Card")
+    model_type = _map_model_type(mi)
+    status = (mi.get("status") or "N/A").upper()
+    if status == "DONE":
+        status = "READY"
+
+    lines = [
+        f"MODEL CARD: {model_name}",
+        "=" * 60,
+        "",
+        f"Target:     {mi.get('target_column', 'N/A')}",
+        f"Type:       {model_type}",
+        f"Status:     {status}",
+        f"Trained:    {mi.get('training_date', 'N/A')}",
+    ]
+
+    # Best metrics
+    roc_auc = _get_metric_value(be, "best_roc_auc", "auc")
+    pr_auc = _get_metric_value(be, "best_pr_auc", "pr_auc")
+    f1 = _get_metric_value(be, "best_roc_auc", "f1")
+    acc = _get_metric_value(be, "best_roc_auc", "accuracy")
+
+    lines.append("")
+    lines.append(
+        f"Accuracy: {format_pct(acc)}  "
+        f"AUC: {format_pct(roc_auc)}  "
+        f"PR-AUC: {format_pct(pr_auc)}  "
+        f"F1: {format_pct(f1)}"
+    )
+
+    # Class imbalance summary
+    if ci.get("total_samples"):
+        lines.append(
+            f"Samples: {ci['total_samples']:,}  "
+            f"Imbalance: {ci.get('imbalance_ratio', 'N/A')}:1"
+        )
+
+    # Model stack summary
+    if es:
+        lines.append(
+            f"Foundation: {format_large_number(es.get('num_parameters'))} params, "
+            f"d_model={es.get('d_model', 'N/A')}"
+        )
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Detailed renderer
+# ---------------------------------------------------------------------------
+
+
+def render_detailed_text(data: Dict[str, Any]) -> str:
+    """Render a full detailed text model card."""
+    sections = [
+        _render_model_identification(data),
+        _render_model_stack(data),
+        _render_best_epochs(data),
+        _render_training_optimization(data),
+        _render_training_dataset(data),
+    ]
+    return "\n".join(s for s in sections if s)
+
+
+def _render_model_identification(data: dict) -> str:
+    mi = data.get("model_identification", {})
+    du = data.get("disk_usage", {})
+    es = data.get("embedding_space", {})
+    be = data.get("best_epochs", {})
+    ci = data.get("class_imbalance", {})
+
+    model_name = mi.get("name", "Model Card")
+    model_type = _map_model_type(mi)
+    status = (mi.get("status") or "N/A").upper()
+    if status == "DONE":
+        status = "READY"
+
+    session_id, job_id = _parse_model_path(du.get("best_model_path"))
+    model_id = session_id or (mi.get("session_id", "N/A")[:20] if mi.get("session_id") else "N/A")
+
+    framework = mi.get("framework", "N/A")
+    framework = re.sub(r"\s+unknown$", "", framework, flags=re.IGNORECASE).strip() or "N/A"
+
+    # Best metrics
+    roc_auc = _get_metric_value(be, "best_roc_auc", "auc")
+    pr_auc = _get_metric_value(be, "best_pr_auc", "pr_auc")
+
+    # PR-AUC lift
+    prevalence = None
+    if ci.get("minority_class_count") and ci.get("total_samples"):
+        prevalence = ci["minority_class_count"] / ci["total_samples"]
+    pr_auc_lift = (pr_auc / prevalence) if (pr_auc and prevalence) else None
+
+    lines = [
+        f"MODEL CARD: {model_name}",
+        "=" * 80,
+        "",
+        "MODEL IDENTIFICATION",
+        "-" * 60,
+        f"  Target Column:  {mi.get('target_column', 'N/A')}",
+        f"  Model Type:     {model_type}",
+        f"  Best ROC-AUC:   {format_pct(roc_auc)}",
+        f"  Best PR-AUC:    {format_pct(pr_auc)}"
+        + (f"  [{pr_auc_lift:.1f}x lift]" if pr_auc_lift else ""),
+        "",
+        f"  Status:         {status}",
+        f"  Training Date:  {mi.get('training_date', 'N/A')}",
+        f"  Model ID:       {model_id}",
+        f"  Cluster:        {(mi.get('compute_cluster') or 'N/A').upper()}",
+        f"  Dims:           {es.get('d_model', 'N/A')}",
+        f"  Framework:      {framework}",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _render_model_stack(data: dict) -> str:
+    es = data.get("embedding_space")
+    if not es:
+        return ""
+
+    sp = data.get("single_predictor") or data.get("predictor") or {}
+    ma = data.get("model_architecture") or {}
+    ms = (data.get("model_stack") or [{}])[0] if data.get("model_stack") else {}
+    ci = data.get("class_imbalance") or {}
+
+    sp_rows = ci.get("total_samples") or ms.get("rows") or sp.get("num_rows", 0)
+    sp_layers = ms.get("layers") or ma.get("predictor_layers") or sp.get("num_layers", 0)
+    sp_params = ms.get("parameters") or ma.get("predictor_parameters") or sp.get("num_parameters", 0)
+
+    lines = [
+        "MODEL STACK",
+        "-" * 60,
+        f"  {'':18s} {'Labeled':>8s} {'Rows':>10s} {'Layers':>10s} {'Parameters':>12s}",
+        f"  {'Predictor':18s} {'Yes':>8s} {sp_rows:>10,} {format_large_number(sp_layers):>10s} {format_large_number(sp_params):>12s}",
+        f"  {'Foundation':18s} {'No':>8s} {es.get('num_rows', 0):>10,} {format_large_number(es.get('num_layers')):>10s} {format_large_number(es.get('num_parameters')):>12s}",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _render_best_epochs(data: dict) -> str:
+    be = data.get("best_epochs")
+    if not be:
+        return ""
+
+    lines = [
+        "MODEL DETAILS",
+        "-" * 60,
+    ]
+
+    for label, key in [("Best ROC-AUC", "best_roc_auc"), ("Best PR-AUC", "best_pr_auc")]:
+        epoch_data = be.get(key)
+        if not epoch_data:
+            continue
+
+        cdm = epoch_data.get("classification_display_metadata") or {}
+        epoch_num = epoch_data.get("epoch") or cdm.get("epoch", "N/A")
+        metrics = cdm.get("classification_metrics") or {}
+
+        lines.append(f"\n  {label} -- Epoch {epoch_num}")
+        lines.append(f"  {'~' * 40}")
+
+        # Metrics table (top 4)
+        for mkey in ["accuracy", "auc", "pr_auc", "f1"]:
+            m = metrics.get(mkey)
+            if not m:
+                continue
+            val = format_pct(m.get("value"))
+            lines.append(f"    {mkey.upper().replace('_', ' '):12s} {val}")
+
+        # Confusion matrix
+        cm = cdm.get("confusion_matrix")
+        if cm:
+            tp, fn, fp, tn = cm.get("tp", 0), cm.get("fn", 0), cm.get("fp", 0), cm.get("tn", 0)
+            total_pos = tp + fn
+            total_neg = tn + fp
+
+            lines.append("")
+            lines.append("    Confusion Matrix:")
+            lines.append(f"                  Pred Pos   Pred Neg")
+            lines.append(f"      Actual Pos    {tp:>5d}      {fn:>5d}")
+            lines.append(f"      Actual Neg    {fp:>5d}      {tn:>5d}")
+
+            # Derived metrics
+            hit_rate = tp / total_pos if total_pos > 0 else 0
+            miss_rate = fn / total_pos if total_pos > 0 else 0
+            specificity = tn / total_neg if total_neg > 0 else 0
+            fpr = fp / total_neg if total_neg > 0 else 0
+            precision = tp / (tp + fp) if (tp + fp) > 0 else 0
+
+            lines.append("")
+            lines.append(f"    Hit Rate (Recall):  {hit_rate * 100:.1f}%   TP/(TP+FN)")
+            lines.append(f"    Miss Rate:          {miss_rate * 100:.1f}%   FN/(TP+FN)")
+            lines.append(f"    Specificity (TNR):  {specificity * 100:.1f}%   TN/(TN+FP)")
+            lines.append(f"    False Alarm (FPR):  {fpr * 100:.1f}%   FP/(TN+FP)")
+            lines.append(f"    Precision (PPV):    {precision * 100:.1f}%   TP/(TP+FP)")
+
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _render_training_optimization(data: dict) -> str:
+    to = data.get("training_optimization")
+    if not to:
+        return ""
+
+    lines = [
+        "TRAINING OPTIMIZATION",
+        "-" * 60,
+    ]
+
+    if to.get("optimization_description"):
+        lines.append(f"  Strategy: {to['optimization_description']}")
+        lines.append("")
+
+    lines.append(f"  Loss Function:         {to.get('loss_function', 'N/A')}")
+    lines.append(f"  Optimization Priority: {(to.get('optimization_priority') or 'N/A').capitalize()}")
+
+    checkpoint = to.get("checkpoint_metric", "")
+    if checkpoint and checkpoint.lower() != "none":
+        lines.append(f"  Checkpoint Metric:     {checkpoint.upper().replace('_', '-')}")
+    else:
+        lines.append(f"  Checkpoint Metric:     Default")
+
+    if to.get("focal_gamma") is not None or to.get("focal_alpha") is not None:
+        lines.append(f"  Focal Loss:            gamma={to.get('focal_gamma', 'N/A')}, alpha={to.get('focal_alpha', 'N/A')}")
+
+    if to.get("class_weights"):
+        lines.append(f"  Class Weights:         [{', '.join(str(w) for w in to['class_weights'])}]")
+
+    cs = to.get("cost_sensitive")
+    if cs:
+        lines.append(f"  Cost-Sensitive:        FP={cs.get('cost_false_positive', 1.0)}, FN={cs.get('cost_false_negative', 1.0)}")
+
+    if to.get("adaptive_loss") is not None:
+        adj = f" ({to['gamma_adjustments']} adjustments)" if to.get("gamma_adjustments") else ""
+        lines.append(f"  Adaptive Loss:         {'Yes' if to['adaptive_loss'] else 'No'}{adj}")
+
+    if to.get("checkpoint_value") is not None:
+        lines.append(f"  Best Checkpoint:       {to['checkpoint_value'] * 100:.2f}% at epoch {to.get('checkpoint_epoch', 'N/A')}")
+
+    if to.get("positive_class") is not None:
+        lines.append(f"  Positive Class:        \"{to['positive_class']}\"")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _render_training_dataset(data: dict) -> str:
+    ci = data.get("class_imbalance") or {}
+    td = data.get("training_dataset") or {}
+
+    if not ci and not td:
+        return ""
+
+    lines = [
+        "TRAINING DATASET",
+        "-" * 60,
+    ]
+
+    if ci.get("train_distribution") or ci.get("class_distribution"):
+        train0 = (ci.get("train_distribution") or {}).get("0", 0)
+        train1 = (ci.get("train_distribution") or {}).get("1", 0)
+        val0 = (ci.get("val_distribution") or {}).get("0", 0)
+        val1 = (ci.get("val_distribution") or {}).get("1", 0)
+        total_train = train0 + train1
+        total_val = val0 + val1
+        total = ci.get("total_samples") or td.get("train_rows") or (total_train + total_val)
+
+        minority = ci.get("minority_class", "1")
+        majority = ci.get("majority_class", "0")
+
+        lines.append(f"  {'':12s} Class \"{minority}\"  Class \"{majority}\"  Total")
+        lines.append(f"  {'Train':12s} {train1:>10,}  {train0:>12,}  {total_train:>8,}")
+        lines.append(f"  {'Validation':12s} {val1:>10,}  {val0:>12,}  {total_val:>8,}")
+        lines.append(f"  {'Total':12s} {ci.get('minority_class_count', train1 + val1):>10,}  {ci.get('majority_class_count', train0 + val0):>12,}  {total:>8,}")
+        lines.append("")
+
+        if ci.get("imbalance_ratio"):
+            minority_pct = (ci.get("minority_class_count", 0) / total * 100) if total else 0
+            lines.append(f"  Imbalance ratio: {ci['imbalance_ratio']}:1 (minority is {minority_pct:.1f}% of data)")
+    elif td.get("train_rows"):
+        lines.append(f"  Training rows: {td['train_rows']:,}")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_metric_value(best_epochs: dict, epoch_key: str, metric_key: str):
+    """Extract a metric value from best_epochs nested structure."""
+    epoch = best_epochs.get(epoch_key) or {}
+    cdm = epoch.get("classification_display_metadata") or {}
+    metrics = cdm.get("classification_metrics") or {}
+    m = metrics.get(metric_key) or {}
+    return m.get("value")
+
+
+def render_to_file(
+    model_card_json: Dict[str, Any],
+    output_path: str,
+    detailed: bool = True,
+) -> str:
+    """Render model card JSON to text file."""
+    text = render_detailed_text(model_card_json) if detailed else render_brief_text(model_card_json)
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(text)
+    return output_path

featrix_modelcard-1.10/featrix_modelcard.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: featrix-modelcard
+Version: 1.10
+Summary: Render Featrix Sphere Model Card JSON to HTML or plain text
+Home-page: https://github.com/featrix/model-card
+Author: Featrix
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# Featrix Model Card - Python Package
+
+Python package for rendering Featrix Model Card JSON to HTML or plain text.
+
+**HTML rendering** delegates to the canonical JavaScript renderer loaded from CDN,
+ensuring the Python output always matches the JS version.
+
+**Text rendering** is a standalone Python implementation for terminal/log output.
+
+## Installation
+
+```bash
+pip install featrix-modelcard
+```
+
+## Usage
+
+### HTML Renderer
+
+The HTML renderer generates a standalone page that loads `model-card.js` from the
+Featrix CDN. The JavaScript renderer handles all layout, styling, and interactivity.
+
+```python
+from featrix_modelcard import render_html, render_html_to_file
+
+# Load model card JSON
+import json
+with open('model_card.json', 'r') as f:
+    model_card = json.load(f)
+
+# Render to file
+render_html_to_file(model_card, 'output.html')
+
+# Render to string
+html = render_html(model_card)
+
+# With 3D sphere visualization
+html = render_html(model_card, show_sphere=True)
+
+# With explicit session ID for sphere
+html = render_html(model_card, show_sphere=True, session_id='my-session-id')
+
+# Override CDN URL (e.g. for local development)
+html = render_html(model_card, cdn_url='http://localhost:8080/model-card.js')
+```
+
+### Text Renderer
+
+```python
+from featrix_modelcard import render_brief_text, render_detailed_text, print_text
+
+# Brief summary
+print_text(model_card, detailed=False)
+
+# Detailed output
+print_text(model_card, detailed=True)
+
+# Get as strings
+brief = render_brief_text(model_card)
+detailed = render_detailed_text(model_card)
+```
+
+## API Reference
+
+### HTML Functions
+
+- `render_html(model_card_json, *, show_sphere=False, session_id=None, cdn_url=None)` -> `str`
+- `render_html_to_file(model_card_json, output_path, *, show_sphere=False, session_id=None, cdn_url=None)` -> `str`
+- `print_html(model_card_json, file=None, **kwargs)` -> `str`
+
+### Text Functions
+
+- `render_brief_text(model_card_json)` -> `str`
+- `render_detailed_text(model_card_json)` -> `str`
+- `render_text_to_file(model_card_json, output_path, detailed=True)` -> `str`
+- `print_text(model_card_json, detailed=True, file=None)` -> `str`
+
+## Architecture
+
+The HTML renderer is a thin wrapper that embeds your model card JSON into a page
+that loads the canonical `FeatrixModelCard` JavaScript renderer from the CDN.
+This means:
+
+- Python HTML output is always in sync with the JS version
+- No rendering logic to maintain in Python
+- All styling, interactivity, and features come from the JS renderer
+- Zero external Python dependencies
+
+The text renderer is a standalone Python implementation for use in terminals,
+logs, and non-browser contexts.

featrix_modelcard-1.10/featrix_modelcard.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+MANIFEST.in
+README.md
+setup.py
+featrix_modelcard/__init__.py
+featrix_modelcard/html_renderer.py
+featrix_modelcard/text_renderer.py
+featrix_modelcard.egg-info/PKG-INFO
+featrix_modelcard.egg-info/SOURCES.txt
+featrix_modelcard.egg-info/dependency_links.txt
+featrix_modelcard.egg-info/top_level.txt

featrix_modelcard-1.10/featrix_modelcard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

featrix_modelcard-1.10/featrix_modelcard.egg-info/top_level.txt

@@ -0,0 +1 @@
+featrix_modelcard

featrix_modelcard-1.10/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

featrix_modelcard-1.10/setup.py

@@ -0,0 +1,30 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="featrix-modelcard",
+    version="1.10",
+    author="Featrix",
+    description="Render Featrix Sphere Model Card JSON to HTML or plain text",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/featrix/model-card",
+    packages=find_packages(),
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "License :: OSI Approved :: MIT License",
+    ],
+    python_requires=">=3.7",
+    install_requires=[],
+)
+