Metadata-Version: 2.4
Name: mlreporter
Version: 0.1.0
Summary: Turn raw ML/DL experiment results into presentation-quality report images, entirely from Python.
Author: Aser Sayyd Abdelzaher
License: MIT
Project-URL: Homepage, https://github.com/AserSayyd2009/mlreport
Project-URL: Repository, https://github.com/AserSayyd2009/mlreport
Project-URL: Changelog, https://github.com/AserSayyd2009/mlreport/blob/main/CHANGELOG.md
Project-URL: Author, https://github.com/AserSayyd2009
Keywords: machine-learning,deep-learning,visualization,matplotlib,reporting,infographic,data-science,kaggle,linkedin
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: matplotlib>=3.7
Requires-Dist: Pillow>=9.0
Requires-Dist: plotly>=5.10
Requires-Dist: scienceplots>=2.0
Requires-Dist: openpyxl>=3.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# mlreport

**Turn raw ML/DL experiment results into presentation-quality report images — entirely from Python.**

No Canva. No PowerPoint. No screenshots of DataFrames. `mlreport` takes a
DataFrame, some metrics, and a theme, and renders a clean, professional
infographic ready for LinkedIn, GitHub, Kaggle, Medium, research papers, and
portfolios.

```python
from mlreport import create_report

create_report(
    dataframe=df,
    title="Hyperparameter Tuning Results",
    subtitle="CNN on MNIST",
    score_col="Accuracy",
    output="report.png",
)
```

That's it — `mlreport` automatically highlights the best value, infers a
takeaway sentence, and lays everything out with zero overlap.

---

## Installation

```bash
pip install -e .
# or, once published:
pip install mlreport
```

Requires Python 3.10+. Dependencies: pandas, numpy, matplotlib, Pillow,
plotly, scienceplots, openpyxl (see `requirements.txt`).

---

## Quick Start

```python
import pandas as pd
from mlreport import create_report, MetricCard

df = pd.DataFrame({
    "Configuration": ["A", "B", "C", "D"],
    "Filters": [32, 64, 64, 128],
    "Dense Units": [128, 256, 128, 512],
    "Learning Rate": [0.001, 0.0005, 0.001, 0.0001],
    "Accuracy": [0.912, 0.941, 0.935, 0.928],
})

create_report(
    dataframe=df,
    title="Hyperparameter Tuning Results",
    subtitle="CNN on MNIST — Grid Search",
    theme="google",
    score_col="Accuracy",
    size_col="Dense Units",
    metric_cards=[
        MetricCard("Best Accuracy", 0.941, "Config B", icon="A", is_percent=True),
        MetricCard("Configs Tested", 4, "Grid search", icon="N", decimals=0),
    ],
    meta={"Framework": "TensorFlow/Keras", "Dataset": "MNIST"},
    footer={"github": "github.com/yourname", "linkedin": "linkedin.com/in/yourname"},
    output="report.png",
)
```

See `examples/` for full runnable scripts, including a Transformer
classification report, a GRU regression report, and a gradient-boosting
benchmark comparison.

---

## Templates

Six ready-made, opinionated templates on top of `create_report`:

| Template | Aspect | Use case |
|---|---|---|
| `linkedin_post` | 1:1 | LinkedIn feed post |
| `github_readme_image` | 16:9 | Embedded in a GitHub README, transparent-bg option |
| `paper_figure` | A4 | Research paper / conference figure (vector PDF) |
| `presentation_slide` | 16:9 | High-contrast conference slide |
| `poster` | A4, 1.6x scale | Academic poster session |
| `portfolio_card` | 4:5 | Personal portfolio project card |
| `minimal_report` | any | Whitespace-forward, no decoration |
| `dark_report` | any | Dark mode / glassmorphism |

```python
from mlreport.templates import linkedin_post

linkedin_post(df, title="Model Results", score_col="Accuracy", output="post.png")
```

---

## Themes

`google`, `deepmind`, `github`, `minimal`, `light`, `dark`, `linkedin`,
`academic`, `presentation`, `modern` — or register your own:

```python
from mlreport import Theme, register_theme, get_palette

register_theme(Theme(
    name="my_brand",
    background="#FFFFFF", panel_background="#F5F5F5",
    primary="#0F172A", secondary="#3B82F6", accent="#F59E0B", negative="#DC2626",
    text_primary="#0F172A", text_secondary="#64748B", grid_color="#E2E8F0",
    chart_palette=get_palette("modern"),
))
```

---

## Charts

`mlreport.charts` covers: horizontal/vertical bar, line, scatter (with
trendline), pie/donut, radar, learning curves (train vs. validation),
confusion matrix, ROC curve, precision-recall curve, feature importance,
benchmark comparison, and hyperparameter comparison — all theme-aware and
composable via the `Report` builder or the `create_chart()` dispatcher.

```python
from mlreport import create_chart, load_theme
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
create_chart("roc", ax, theme=load_theme("dark"), fpr=fpr, tpr=tpr, auc=0.93)
```

---

## Building a custom report

For full control over section order, use the `Report` builder directly:

```python
from mlreport import Report, load_theme, create_chart

report = Report(theme=load_theme("deepmind"), aspect="4:5")
report.add_header("Emotion Classification", subtitle="Transformer Encoder")
report.add_chart(lambda ax, th: create_chart("learning_curve", ax, theme=th,
                                              epochs=epochs, train=train_acc, val=val_acc))
report.add_table(results_df)
report.add_notes("Validation accuracy reached 91% by epoch 10.")
report.add_footer(github="github.com/yourname")
report.render().save("report.png")
```

---

## Export

```python
rendered = report.render()
rendered.save("report.png", dpi=300, transparent=False)
rendered.save_many("report", formats=["png", "pdf", "svg"])
```

DPI presets: `Exporter.from_preset("screen"|"web"|"print"|"hq")` → 100 / 150 / 300 / 600 DPI.

---

## Testing

```bash
pip install -e ".[dev]"
pytest
```

---

## Roadmap

- [ ] Real bundled brand-logo icon set (opt-in, licensing-cleared)
- [ ] Automatic font download for Inter/Roboto/JetBrains Mono
- [ ] Bounding-box / segmentation-mask renderer for CV reports
- [ ] Plotly-backed interactive HTML export
- [ ] `mlreport init` CLI scaffolding command

## License

MIT — see `LICENSE`.
