firstlook 0.1.0__tar.gz

firstlook-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Rajhans
+
+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.

firstlook-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: firstlook
+Version: 0.1.0
+Summary: Drop in any dataframe and get models worth trying plus the right charts.
+Author: Siddhant Rajhans
+License: MIT
+Project-URL: Homepage, https://github.com/siddhant-rajhans/firstlook
+Project-URL: Issues, https://github.com/siddhant-rajhans/firstlook/issues
+Keywords: eda,automl,visualization,plotly,data-science,machine-learning
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: numpy>=1.23
+Requires-Dist: plotly>=5.0
+Provides-Extra: fit
+Requires-Dist: scikit-learn>=1.1; extra == "fit"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: scikit-learn>=1.1; extra == "dev"
+Dynamic: license-file
+
+# firstlook
+
+Drop in any dataframe and get models worth trying plus the right charts. The first look you take at any dataset, done for you.
+
+```python
+import firstlook
+firstlook.at(df, target="species")
+```
+
+One call and you get three things back:
+
+1. **The problem type:** regression, classification, or clustering, inferred from the data.
+2. **Models to try:** ranked, with a one-line reason each, plus data-aware warnings (class imbalance, categoricals that need encoding, missing values, too few rows).
+3. **The right charts:** a dark, interactive Plotly dashboard that picks the chart per column: bar/histogram for the target, a scatter colored by class (or feature-vs-target for regression), a correlation heatmap, and a closer look.
+
+It works in Jupyter (rich card + interactive charts render inline) and in plain scripts (prints the recommendation; `report.to_html("out.html")` for the visuals).
+
+**See it on real data:** [`examples/`](examples/) runs the full understand → visualize → model arc on three datasets — breast cancer, diabetes, and a messy churn set — with the dashboards rendered.
+
+## Why
+
+Every project starts the same way: load the data, squint at it, remember which chart goes with which column, half-remember the sklearn cheat-sheet. `firstlook` does that opening move for you so you can get to the actual modeling without writing a wall of matplotlib.
+
+## Install
+
+```bash
+pip install firstlook
+```
+
+From source, for development:
+
+```bash
+git clone https://github.com/siddhant-rajhans/firstlook
+cd firstlook
+pip install -e ".[dev]"
+```
+
+## Use
+
+```python
+import firstlook
+from sklearn.datasets import load_iris
+
+iris = load_iris(as_frame=True).frame
+report = firstlook.at(iris, target="target")
+
+report.task          # "classification"
+report.start         # "LogisticRegression"
+report.models        # [("LogisticRegression", "..."), ...]
+report.notes         # ["3 classes", ...]
+report.figure        # the Plotly figure (restyle or export it)
+report.to_html("iris.html")
+```
+
+Need just one piece?
+
+```python
+firstlook.detect_task(df, target="price")   # "regression"
+firstlook.recommend(df, target="price")     # a Recommendation (task, start, models, notes)
+firstlook.visualize(df, target="price")     # a Plotly figure
+```
+
+The dark theme is also a registered Plotly template you can use on your own figures:
+
+```python
+fig.update_layout(template="firstlook")
+```
+
+(`firstlook.at` and `firstlook.play` are the same call.)
+
+## Get a baseline score, too
+
+Pass `fit=True` and `firstlook` trains the recommended model and cross-validates it, so the recommendation comes with a real score attached. Preprocessing (impute, scale, one-hot) is built in, so it fits straight on messy data:
+
+```python
+report = firstlook.at(df, target="price", fit=True)
+report.baseline      # Baseline(model="LinearRegression", metric="R2", score=0.97, ...)
+```
+
+Needs scikit-learn: `pip install "firstlook[fit]"`.
+
+## What it handles today
+
+Tabular regression, classification, and clustering. Image / text / time-series problems are out of scope for now.
+
+## Roadmap
+
+- More chart types (pair plots, missingness maps, target-vs-time).
+- A light/lab theme alongside the dark one.
+- Image / text / time-series support beyond tabular.
+
+## License
+
+MIT

firstlook-0.1.0/README.md

@@ -0,0 +1,94 @@
+# firstlook
+
+Drop in any dataframe and get models worth trying plus the right charts. The first look you take at any dataset, done for you.
+
+```python
+import firstlook
+firstlook.at(df, target="species")
+```
+
+One call and you get three things back:
+
+1. **The problem type:** regression, classification, or clustering, inferred from the data.
+2. **Models to try:** ranked, with a one-line reason each, plus data-aware warnings (class imbalance, categoricals that need encoding, missing values, too few rows).
+3. **The right charts:** a dark, interactive Plotly dashboard that picks the chart per column: bar/histogram for the target, a scatter colored by class (or feature-vs-target for regression), a correlation heatmap, and a closer look.
+
+It works in Jupyter (rich card + interactive charts render inline) and in plain scripts (prints the recommendation; `report.to_html("out.html")` for the visuals).
+
+**See it on real data:** [`examples/`](examples/) runs the full understand → visualize → model arc on three datasets — breast cancer, diabetes, and a messy churn set — with the dashboards rendered.
+
+## Why
+
+Every project starts the same way: load the data, squint at it, remember which chart goes with which column, half-remember the sklearn cheat-sheet. `firstlook` does that opening move for you so you can get to the actual modeling without writing a wall of matplotlib.
+
+## Install
+
+```bash
+pip install firstlook
+```
+
+From source, for development:
+
+```bash
+git clone https://github.com/siddhant-rajhans/firstlook
+cd firstlook
+pip install -e ".[dev]"
+```
+
+## Use
+
+```python
+import firstlook
+from sklearn.datasets import load_iris
+
+iris = load_iris(as_frame=True).frame
+report = firstlook.at(iris, target="target")
+
+report.task          # "classification"
+report.start         # "LogisticRegression"
+report.models        # [("LogisticRegression", "..."), ...]
+report.notes         # ["3 classes", ...]
+report.figure        # the Plotly figure (restyle or export it)
+report.to_html("iris.html")
+```
+
+Need just one piece?
+
+```python
+firstlook.detect_task(df, target="price")   # "regression"
+firstlook.recommend(df, target="price")     # a Recommendation (task, start, models, notes)
+firstlook.visualize(df, target="price")     # a Plotly figure
+```
+
+The dark theme is also a registered Plotly template you can use on your own figures:
+
+```python
+fig.update_layout(template="firstlook")
+```
+
+(`firstlook.at` and `firstlook.play` are the same call.)
+
+## Get a baseline score, too
+
+Pass `fit=True` and `firstlook` trains the recommended model and cross-validates it, so the recommendation comes with a real score attached. Preprocessing (impute, scale, one-hot) is built in, so it fits straight on messy data:
+
+```python
+report = firstlook.at(df, target="price", fit=True)
+report.baseline      # Baseline(model="LinearRegression", metric="R2", score=0.97, ...)
+```
+
+Needs scikit-learn: `pip install "firstlook[fit]"`.
+
+## What it handles today
+
+Tabular regression, classification, and clustering. Image / text / time-series problems are out of scope for now.
+
+## Roadmap
+
+- More chart types (pair plots, missingness maps, target-vs-time).
+- A light/lab theme alongside the dark one.
+- Image / text / time-series support beyond tabular.
+
+## License
+
+MIT

firstlook-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "firstlook"
+version = "0.1.0"
+description = "Drop in any dataframe and get models worth trying plus the right charts."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Siddhant Rajhans" }]
+keywords = ["eda", "automl", "visualization", "plotly", "data-science", "machine-learning"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "pandas>=1.5",
+    "numpy>=1.23",
+    "plotly>=5.0",
+]
+
+[project.optional-dependencies]
+fit = ["scikit-learn>=1.1"]
+dev = ["pytest>=7", "scikit-learn>=1.1"]
+
+[project.urls]
+Homepage = "https://github.com/siddhant-rajhans/firstlook"
+Issues = "https://github.com/siddhant-rajhans/firstlook/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

firstlook-0.1.0/setup.cfg

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

firstlook-0.1.0/src/firstlook/__init__.py

@@ -0,0 +1,24 @@
+"""firstlook — drop in any dataframe, get models to try and the right charts.
+
+    import firstlook
+    firstlook.at(df, target="species")
+
+That one call detects the problem type, recommends models (with reasons and
+data-aware warnings), and renders a dark, interactive Plotly dashboard. It's
+the first look you take at any dataset, done for you.
+"""
+from . import theme  # noqa: F401  (registers the "firstlook" Plotly template on import)
+from .detect import detect_task
+from .recommend import recommend, Recommendation
+from .visualize import visualize
+from .report import play, Report
+from .baseline import fit_baseline, Baseline
+from .theme import THEME
+
+at = play  # headline alias: firstlook.at(df, target=...)
+
+__version__ = "0.1.0"
+__all__ = [
+    "at", "play", "recommend", "visualize", "detect_task", "fit_baseline",
+    "Report", "Recommendation", "Baseline", "THEME", "__version__",
+]

firstlook-0.1.0/src/firstlook/baseline.py

@@ -0,0 +1,88 @@
+"""Train the recommended baseline model and report an honest score.
+
+Needs scikit-learn (the ``fit`` / ``dev`` extra). Preprocessing is built into
+the pipeline (median-impute + scale numerics, most-frequent-impute + one-hot
+categoricals), so it fits straight on the messy data the recommender only warns
+about. Scoring is cross-validated, so a tiny test split can't flatter or wreck it.
+"""
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Baseline:
+    model: Optional[str]
+    metric: Optional[str]
+    score: Optional[float]
+    std: Optional[float] = None
+    cv: Optional[int] = None
+    note: Optional[str] = None
+
+    def __str__(self):
+        if self.score is None:
+            return f"baseline: {self.note}"
+        return (f"baseline: {self.model}  {self.metric} {self.score:.3f} "
+                f"+/- {self.std:.3f}  ({self.cv}-fold CV)")
+
+
+def fit_baseline(df, target, task):
+    """Cross-validate the recommended start model; return a :class:`Baseline`."""
+    if task == "clustering" or target is None:
+        return Baseline(None, None, None, note="no target, nothing to fit")
+    try:
+        from sklearn.linear_model import LinearRegression, LogisticRegression
+        from sklearn.model_selection import cross_val_score
+        from sklearn.pipeline import Pipeline
+        from sklearn.compose import ColumnTransformer
+        from sklearn.preprocessing import OneHotEncoder, StandardScaler
+        from sklearn.impute import SimpleImputer
+    except ImportError as e:
+        raise ImportError(
+            "baseline fitting needs scikit-learn; install it with "
+            "`pip install 'firstlook[fit]'`"
+        ) from e
+
+    data = df.dropna(subset=[target])
+    y = data[target]
+    X = data.drop(columns=[target])
+    n = len(data)
+    if n < 10 or X.shape[1] == 0:
+        return Baseline(None, None, None, note="too few rows to score reliably")
+
+    num = X.select_dtypes(include="number").columns.tolist()
+    cat = [c for c in X.columns if c not in num]
+    pre = ColumnTransformer(
+        transformers=[
+            ("num", Pipeline([("imp", SimpleImputer(strategy="median")),
+                              ("sc", StandardScaler())]), num),
+            ("cat", Pipeline([("imp", SimpleImputer(strategy="most_frequent")),
+                              ("oh", OneHotEncoder(handle_unknown="ignore"))]), cat),
+        ],
+        remainder="drop",
+    )
+
+    if task == "regression":
+        model, name, metric, scoring = LinearRegression(), "LinearRegression", "R2", "r2"
+        cv = min(5, max(2, n // 4))
+    else:
+        vc = y.value_counts()
+        per_class = int(vc.min())
+        if per_class < 2:
+            return Baseline("LogisticRegression", "accuracy", None,
+                            note="a class has <2 samples; can't cross-validate")
+        name = "LogisticRegression"
+        cv = min(5, max(2, per_class))
+        # plain accuracy flatters imbalanced data (a majority-only guesser scores
+        # high), so on imbalance we both weight the classes (the tool's own advice)
+        # and score with balanced accuracy. Otherwise plain LogisticRegression + accuracy.
+        if (vc.max() / len(y)) > 0.7:
+            model = LogisticRegression(max_iter=1000, class_weight="balanced")
+            metric, scoring = "balanced accuracy", "balanced_accuracy"
+        else:
+            model = LogisticRegression(max_iter=1000)
+            metric, scoring = "accuracy", "accuracy"
+
+    pipe = Pipeline([("pre", pre), ("model", model)])
+    scores = cross_val_score(pipe, X, y, cv=cv, scoring=scoring)
+    return Baseline(model=name, metric=metric, score=float(scores.mean()),
+                    std=float(scores.std()), cv=cv)

firstlook-0.1.0/src/firstlook/detect.py

@@ -0,0 +1,36 @@
+"""Figure out what kind of problem a dataframe poses."""
+import pandas as pd
+
+TASKS = ("regression", "classification", "clustering")
+
+
+def detect_task(df, target=None):
+    """Return ``"regression"``, ``"classification"``, or ``"clustering"``.
+
+    No target -> clustering. A non-numeric target -> classification. A numeric
+    target is classification only when it has few distinct values relative to
+    the number of rows (encoded labels), otherwise regression. The ratio check
+    is what stops a small regression set (e.g. 7 distinct MPG values in 7 rows)
+    from being mistaken for 7-class classification.
+    """
+    if target is None:
+        return "clustering"
+    if target not in df.columns:
+        raise KeyError(f"target {target!r} is not a column. Columns: {list(df.columns)}")
+
+    y = df[target].dropna()
+    if y.empty:
+        return "clustering"
+
+    if pd.api.types.is_bool_dtype(y):
+        return "classification"
+    if not pd.api.types.is_numeric_dtype(y):
+        return "classification"
+
+    n, nun = len(y), y.nunique()
+    if nun == 2:
+        return "classification"  # binary is classification regardless of dtype/size
+    if pd.api.types.is_float_dtype(y):
+        return "classification" if (nun <= 10 and nun / n < 0.05) else "regression"
+    # integer target
+    return "classification" if (nun <= 20 and nun / n < 0.2) else "regression"

firstlook-0.1.0/src/firstlook/recommend.py

@@ -0,0 +1,81 @@
+"""Recommend models to try, with reasons and data-aware warnings.
+
+The model lists follow scikit-learn's algorithm cheat-sheet; the warnings come
+from looking at the actual data (imbalance, categoricals, missing values, tiny n).
+"""
+from dataclasses import dataclass
+from typing import List, Tuple
+
+import pandas as pd
+
+from .detect import detect_task
+
+_REGRESSION = [
+    ("LinearRegression", "interpretable baseline, the right first try"),
+    ("Ridge / Lasso", "linear + regularization; Lasso also drops weak features"),
+    ("RandomForestRegressor", "non-linear, handles interactions, little tuning"),
+    ("GradientBoosting / XGBoost", "usually the top scorer on tabular data"),
+]
+
+_CLASSIFICATION = [
+    ("LogisticRegression", "interpretable baseline, gives probabilities"),
+    ("KNeighborsClassifier", "simple, non-linear, nothing to train"),
+    ("RandomForestClassifier", "strong default, handles mixed features"),
+    ("GradientBoosting / XGBoost", "usually best on tabular data"),
+]
+
+_CLUSTERING = [
+    ("KMeans", "the default when you roughly know how many groups"),
+    ("DBSCAN", "arbitrary shapes, no k, flags outliers"),
+    ("PCA -> cluster", "reduce dimensions first if many features"),
+]
+
+
+@dataclass
+class Recommendation:
+    task: str
+    start: str
+    models: List[Tuple[str, str]]
+    notes: List[str]
+
+    def __str__(self):  # plain-text rendering for scripts / print()
+        lines = [f"task: {self.task}    start with: {self.start}", "", "models to try:"]
+        lines += [f"  - {m:28} {r}" for m, r in self.models]
+        if self.notes:
+            lines += ["", "watch out for:"] + [f"  -> {n}" for n in self.notes]
+        return "\n".join(lines)
+
+
+def recommend(df, target=None, task=None):
+    """Return a :class:`Recommendation` for ``df`` predicting ``target``."""
+    task = task or detect_task(df, target)
+    n = len(df)
+    feats = [c for c in df.columns if c != target]
+    n_cat = sum(not pd.api.types.is_numeric_dtype(df[c]) for c in feats)
+    notes = []
+
+    if n < 50:
+        notes.append(f"only {n} rows - any model will be shaky; more data is the biggest win")
+
+    if task == "regression":
+        start, models = "LinearRegression", _REGRESSION
+    elif task == "classification":
+        start, models = "LogisticRegression", _CLASSIFICATION
+        if target is not None:
+            y = df[target]
+            notes.append(f"{y.nunique()} classes")
+            vc = y.value_counts(normalize=True)
+            if len(vc) and vc.max() > 0.7:
+                notes.append(
+                    f"imbalanced - {vc.idxmax()!r} is {vc.max()*100:.0f}% of rows; "
+                    "watch recall, try class_weight"
+                )
+    else:
+        start, models = "KMeans", _CLUSTERING
+
+    if n_cat:
+        notes.append(f"{n_cat} categorical feature(s) - encode (one-hot/ordinal) before fitting")
+    if df.isna().any().any():
+        notes.append("missing values present - impute or drop first")
+
+    return Recommendation(task=task, start=start, models=models, notes=notes)

firstlook-0.1.0/src/firstlook/report.py

@@ -0,0 +1,123 @@
+"""``play()`` / ``at()`` — the one call that ties it all together."""
+from dataclasses import dataclass
+
+from . import theme
+from .detect import detect_task
+from .recommend import recommend, Recommendation
+from .visualize import visualize
+from .baseline import fit_baseline, Baseline
+
+
+def _in_notebook():
+    try:
+        from IPython import get_ipython
+        ip = get_ipython()
+        return ip is not None and ip.__class__.__name__ == "ZMQInteractiveShell"
+    except Exception:
+        return False
+
+
+def _card_html(title, rec, shape, target, baseline=None):
+    accent = theme.ACCENT.get(rec.task, theme.CYAN)
+    models = "".join(
+        f'<li><span style="color:{theme.CYAN};font-family:monospace;font-weight:600">{m}</span>'
+        f' <span style="color:#b9b9cc">{r}</span></li>' for m, r in rec.models)
+    notes = "".join(f'<li style="color:#cfcfe0"><span style="color:{accent}">&rarr; </span>{n}</li>'
+                    for n in rec.notes) or '<li style="color:#cfcfe0">clean and ready to model.</li>'
+    base = ""
+    if baseline is not None and baseline.score is not None:
+        base = (f'<div style="margin-top:14px;padding:10px 14px;background:#11112a;border-radius:8px;'
+                f'font-size:13.5px"><span style="color:#8a8aa0">baseline</span> &nbsp;'
+                f'<span style="color:{theme.CYAN};font-family:monospace">{baseline.model}</span> &middot; '
+                f'{baseline.metric} <span style="color:{accent};font-weight:700">{baseline.score:.3f}</span> '
+                f'<span style="color:#8a8aa0">&plusmn;{baseline.std:.3f} ({baseline.cv}-fold CV)</span></div>')
+    elif baseline is not None and baseline.note:
+        base = f'<div style="margin-top:14px;font-size:13px;color:#8a8aa0">baseline: {baseline.note}</div>'
+    return f"""<div style="background:{theme.BG};color:{theme.INK};font-family:Inter,system-ui,sans-serif;
+ border-radius:12px;padding:18px 20px;max-width:680px">
+ <div style="font-size:20px;font-weight:800;letter-spacing:-.02em">{title}</div>
+ <div style="margin:6px 0 14px;font-size:13px;color:#8a8aa0">
+   <span style="background:{accent};color:#08080f;font-weight:700;font-size:11px;padding:3px 11px;
+    border-radius:999px;text-transform:uppercase;letter-spacing:.08em">{rec.task}</span>
+   &nbsp; {shape[0]} rows &middot; {shape[1]} cols &middot; target: <code>{target}</code></div>
+ <div style="display:grid;grid-template-columns:1fr 1fr;gap:16px">
+  <div><div style="font-size:12px;letter-spacing:.1em;text-transform:uppercase;color:#8a8aa0;
+    margin-bottom:8px">models to try</div>
+   <ul style="list-style:none;margin:0;padding:0;font-size:13.5px;line-height:1.5">{models}</ul>
+   <div style="margin-top:10px;font-size:13px;color:#8a8aa0">start with
+    <span style="color:{accent};font-weight:700">{rec.start}</span></div></div>
+  <div><div style="font-size:12px;letter-spacing:.1em;text-transform:uppercase;color:#8a8aa0;
+    margin-bottom:8px">watch out for</div>
+   <ul style="list-style:none;margin:0;padding:0;font-size:13.5px;line-height:1.5">{notes}</ul></div>
+ </div>{base}</div>"""
+
+
+@dataclass
+class Report:
+    title: str
+    task: str
+    recommendation: Recommendation
+    figure: object
+    shape: tuple
+    target: str
+    baseline: object = None
+
+    @property
+    def start(self):
+        return self.recommendation.start
+
+    @property
+    def models(self):
+        return self.recommendation.models
+
+    @property
+    def notes(self):
+        return self.recommendation.notes
+
+    def show(self):
+        """Render in a notebook (rich card + interactive charts) or print (scripts)."""
+        if _in_notebook():
+            from IPython.display import HTML, display
+            display(HTML(_card_html(self.title, self.recommendation, self.shape, self.target, self.baseline)))
+            self.figure.show()
+        else:
+            print(self.title)
+            print(self.recommendation)
+            if self.baseline is not None:
+                print("\n" + str(self.baseline))
+        return self
+
+    def to_html(self, path):
+        """Write a standalone dark dashboard (recommendations + charts) to ``path``."""
+        chart = self.figure.to_html(full_html=False, include_plotlyjs="cdn",
+                                    config={"displayModeBar": False})
+        card = _card_html(self.title, self.recommendation, self.shape, self.target, self.baseline)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(f'<!DOCTYPE html><html><head><meta charset="UTF-8"><title>{self.title}</title></head>'
+                    f'<body style="margin:0;background:{theme.BG}">'
+                    f'<div style="max-width:1080px;margin:0 auto;padding:24px">{card}{chart}</div>'
+                    f"</body></html>")
+        return path
+
+    def _repr_html_(self):
+        return _card_html(self.title, self.recommendation, self.shape, self.target, self.baseline)
+
+
+def play(df, target=None, title=None, show=True, fit=False):
+    """Inspect ``df``: detect the task, recommend models, and chart the data.
+
+    Set ``fit=True`` to also cross-validate the recommended baseline model and
+    report a score (needs scikit-learn: ``pip install 'firstlook[fit]'``).
+
+    Returns a :class:`Report` (``.task``, ``.start``, ``.models``, ``.notes``,
+    ``.figure``, ``.baseline``, ``.to_html(path)``).
+    """
+    task = detect_task(df, target)
+    rec = recommend(df, target, task)
+    fig = visualize(df, target, task)
+    baseline = fit_baseline(df, target, task) if fit else None
+    report = Report(title=title or "your data", task=task, recommendation=rec,
+                    figure=fig, shape=df.shape, target=target, baseline=baseline)
+    if show:
+        report.show()
+    return report

firstlook-0.1.0/src/firstlook/theme.py

@@ -0,0 +1,49 @@
+"""Brand theme — a registered Plotly template plus the raw palette.
+
+Importing firstlook registers a ``"firstlook"`` Plotly template, so any figure
+(yours or ours) can opt into the dark, high-contrast look with
+``fig.update_layout(template="firstlook")``.
+"""
+import plotly.graph_objects as go
+import plotly.io as pio
+
+BG = "#080814"
+PANEL = "#0c0c1f"
+INK = "#e9e9f4"
+MUTED = "#9a9ab0"
+GRID = "rgba(255,255,255,0.07)"
+
+CYAN = "#00E5FF"
+GOLD = "#FFD27F"
+PINK = "#FF4081"
+PURPLE = "#7C4DFF"
+GREEN = "#00E676"
+AMBER = "#FFAB00"
+
+PALETTE = [CYAN, PINK, GOLD, PURPLE, GREEN, AMBER]
+
+ACCENT = {"classification": PINK, "regression": GOLD, "clustering": PURPLE}
+
+THEME = {
+    "bg": BG, "panel": PANEL, "ink": INK, "muted": MUTED, "grid": GRID,
+    "palette": PALETTE, "cyan": CYAN, "gold": GOLD, "pink": PINK,
+    "purple": PURPLE, "green": GREEN, "amber": AMBER,
+}
+
+
+def _register():
+    tpl = go.layout.Template()
+    tpl.layout = go.Layout(
+        paper_bgcolor=BG,
+        plot_bgcolor=PANEL,
+        font=dict(color=INK, family="Inter, system-ui, -apple-system, sans-serif"),
+        colorway=PALETTE,
+        xaxis=dict(gridcolor=GRID, zerolinecolor=GRID, color=MUTED),
+        yaxis=dict(gridcolor=GRID, zerolinecolor=GRID, color=MUTED),
+        title=dict(font=dict(color=INK)),
+        legend=dict(bgcolor="rgba(0,0,0,0)"),
+    )
+    pio.templates["firstlook"] = tpl
+
+
+_register()

firstlook-0.1.0/src/firstlook/visualize.py

@@ -0,0 +1,125 @@
+"""Auto-pick the right charts for a dataframe and return one Plotly figure."""
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+
+from . import theme
+from .detect import detect_task
+
+PALETTE = theme.PALETTE
+CYAN, GOLD = theme.CYAN, theme.GOLD
+
+
+def _numeric_feats(df, target):
+    return [c for c in df.columns if c != target and pd.api.types.is_numeric_dtype(df[c])]
+
+
+def _corr_ratio(cats, values):
+    """Correlation ratio (eta-squared): association between a categorical
+    target and a numeric feature — between-group variance over total variance."""
+    d = pd.DataFrame({"c": cats.values, "v": pd.to_numeric(values, errors="coerce").values}).dropna()
+    if d.empty:
+        return 0.0
+    grand = d["v"].mean()
+    ss_total = ((d["v"] - grand) ** 2).sum()
+    if ss_total == 0:
+        return 0.0
+    ss_between = sum(len(g) * (g["v"].mean() - grand) ** 2 for _, g in d.groupby("c"))
+    return ss_between / ss_total
+
+
+def _rank_features(df, target, num, task):
+    """Order numeric features by association with the target.
+
+    Classification uses the correlation ratio (eta-squared) — the right measure
+    for a categorical target. Regression uses |Pearson r|. Ranking features by
+    correlation with integer-encoded class labels would impose a fake ordering
+    on the classes, so we don't.
+    """
+    if target is None or not num:
+        return num
+    y = df[target]
+    if task == "classification":
+        score = {c: _corr_ratio(y, df[c]) for c in num}
+    else:
+        def pear(c):
+            try:
+                return abs(np.corrcoef(df[c].astype(float), y.astype(float))[0, 1])
+            except Exception:
+                return 0.0
+        score = {c: pear(c) for c in num}
+    return sorted(num, key=lambda c: np.nan_to_num(score[c]), reverse=True)
+
+
+def visualize(df, target=None, task=None):
+    """Return a 2x2 Plotly dashboard chosen to fit the data and task."""
+    task = task or detect_task(df, target)
+    num = _numeric_feats(df, target)
+    ranked = _rank_features(df, target, num, task)
+
+    titles = [f"target: {target}" if target else "first feature",
+              "the key relationship", "feature correlations", "a closer look"]
+    fig = make_subplots(
+        rows=2, cols=2, subplot_titles=titles,
+        specs=[[{"type": "xy"}, {"type": "xy"}], [{"type": "heatmap"}, {"type": "xy"}]],
+        vertical_spacing=0.16, horizontal_spacing=0.12,
+    )
+
+    # P1 - target (or first feature) distribution
+    if task == "classification" and target is not None:
+        vc = df[target].value_counts()
+        fig.add_trace(go.Bar(x=[str(i) for i in vc.index], y=vc.values,
+                             marker_color=PALETTE[: len(vc)], showlegend=False), 1, 1)
+    else:
+        col = target if (target and pd.api.types.is_numeric_dtype(df[target])) else (ranked[0] if ranked else None)
+        if col is not None:
+            fig.add_trace(go.Histogram(x=df[col], marker_color=CYAN, showlegend=False), 1, 1)
+
+    # P2 - the key relationship
+    if task == "classification" and target is not None and len(ranked) >= 2:
+        f1, f2 = ranked[0], ranked[1]
+        for i, (cls, g) in enumerate(df.groupby(target)):
+            fig.add_trace(go.Scatter(x=g[f1], y=g[f2], mode="markers", name=str(cls),
+                                     marker=dict(size=8, color=PALETTE[i % len(PALETTE)],
+                                                 line=dict(color="#04101a", width=0.5))), 1, 2)
+        fig.update_xaxes(title_text=f1, row=1, col=2)
+        fig.update_yaxes(title_text=f2, row=1, col=2)
+    elif target is not None and ranked:
+        f1 = ranked[0]
+        fig.add_trace(go.Scatter(x=df[f1], y=df[target], mode="markers", showlegend=False,
+                                 marker=dict(size=9, color=CYAN, line=dict(color="#04101a", width=0.5))), 1, 2)
+        fig.update_xaxes(title_text=f1, row=1, col=2)
+        fig.update_yaxes(title_text=str(target), row=1, col=2)
+    elif len(ranked) >= 2:  # clustering / no target
+        fig.add_trace(go.Scatter(x=df[ranked[0]], y=df[ranked[1]], mode="markers", showlegend=False,
+                                 marker=dict(size=8, color=theme.PURPLE)), 1, 2)
+        fig.update_xaxes(title_text=ranked[0], row=1, col=2)
+        fig.update_yaxes(title_text=ranked[1], row=1, col=2)
+
+    # P3 - correlation heatmap
+    cols = num + ([target] if (target and pd.api.types.is_numeric_dtype(df[target])) else [])
+    if len(cols) >= 2:
+        corr = df[cols].corr()
+        fig.add_trace(go.Heatmap(z=corr.values, x=cols, y=cols, zmin=-1, zmax=1,
+                                 colorscale=[[0, theme.PINK], [0.5, "#1a1a2e"], [1, CYAN]],
+                                 showscale=False), 2, 1)
+
+    # P4 - a closer look
+    if task == "classification" and target is not None and ranked:
+        f1 = ranked[0]
+        for i, (cls, g) in enumerate(df.groupby(target)):
+            fig.add_trace(go.Box(y=g[f1], name=str(cls), marker_color=PALETTE[i % len(PALETTE)],
+                                 showlegend=False), 2, 2)
+        fig.update_yaxes(title_text=f1, row=2, col=2)
+    elif ranked:
+        f = ranked[1] if len(ranked) >= 2 else ranked[0]
+        fig.add_trace(go.Histogram(x=df[f], marker_color=GOLD, showlegend=False), 2, 2)
+        fig.update_xaxes(title_text=f, row=2, col=2)
+
+    fig.update_layout(template="firstlook", height=620, margin=dict(l=55, r=30, t=50, b=45),
+                     legend=dict(font=dict(size=11)))
+    for a in fig.layout.annotations:
+        a.font.color = theme.INK
+        a.font.size = 13
+    return fig

firstlook-0.1.0/src/firstlook.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: firstlook
+Version: 0.1.0
+Summary: Drop in any dataframe and get models worth trying plus the right charts.
+Author: Siddhant Rajhans
+License: MIT
+Project-URL: Homepage, https://github.com/siddhant-rajhans/firstlook
+Project-URL: Issues, https://github.com/siddhant-rajhans/firstlook/issues
+Keywords: eda,automl,visualization,plotly,data-science,machine-learning
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: numpy>=1.23
+Requires-Dist: plotly>=5.0
+Provides-Extra: fit
+Requires-Dist: scikit-learn>=1.1; extra == "fit"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: scikit-learn>=1.1; extra == "dev"
+Dynamic: license-file
+
+# firstlook
+
+Drop in any dataframe and get models worth trying plus the right charts. The first look you take at any dataset, done for you.
+
+```python
+import firstlook
+firstlook.at(df, target="species")
+```
+
+One call and you get three things back:
+
+1. **The problem type:** regression, classification, or clustering, inferred from the data.
+2. **Models to try:** ranked, with a one-line reason each, plus data-aware warnings (class imbalance, categoricals that need encoding, missing values, too few rows).
+3. **The right charts:** a dark, interactive Plotly dashboard that picks the chart per column: bar/histogram for the target, a scatter colored by class (or feature-vs-target for regression), a correlation heatmap, and a closer look.
+
+It works in Jupyter (rich card + interactive charts render inline) and in plain scripts (prints the recommendation; `report.to_html("out.html")` for the visuals).
+
+**See it on real data:** [`examples/`](examples/) runs the full understand → visualize → model arc on three datasets — breast cancer, diabetes, and a messy churn set — with the dashboards rendered.
+
+## Why
+
+Every project starts the same way: load the data, squint at it, remember which chart goes with which column, half-remember the sklearn cheat-sheet. `firstlook` does that opening move for you so you can get to the actual modeling without writing a wall of matplotlib.
+
+## Install
+
+```bash
+pip install firstlook
+```
+
+From source, for development:
+
+```bash
+git clone https://github.com/siddhant-rajhans/firstlook
+cd firstlook
+pip install -e ".[dev]"
+```
+
+## Use
+
+```python
+import firstlook
+from sklearn.datasets import load_iris
+
+iris = load_iris(as_frame=True).frame
+report = firstlook.at(iris, target="target")
+
+report.task          # "classification"
+report.start         # "LogisticRegression"
+report.models        # [("LogisticRegression", "..."), ...]
+report.notes         # ["3 classes", ...]
+report.figure        # the Plotly figure (restyle or export it)
+report.to_html("iris.html")
+```
+
+Need just one piece?
+
+```python
+firstlook.detect_task(df, target="price")   # "regression"
+firstlook.recommend(df, target="price")     # a Recommendation (task, start, models, notes)
+firstlook.visualize(df, target="price")     # a Plotly figure
+```
+
+The dark theme is also a registered Plotly template you can use on your own figures:
+
+```python
+fig.update_layout(template="firstlook")
+```
+
+(`firstlook.at` and `firstlook.play` are the same call.)
+
+## Get a baseline score, too
+
+Pass `fit=True` and `firstlook` trains the recommended model and cross-validates it, so the recommendation comes with a real score attached. Preprocessing (impute, scale, one-hot) is built in, so it fits straight on messy data:
+
+```python
+report = firstlook.at(df, target="price", fit=True)
+report.baseline      # Baseline(model="LinearRegression", metric="R2", score=0.97, ...)
+```
+
+Needs scikit-learn: `pip install "firstlook[fit]"`.
+
+## What it handles today
+
+Tabular regression, classification, and clustering. Image / text / time-series problems are out of scope for now.
+
+## Roadmap
+
+- More chart types (pair plots, missingness maps, target-vs-time).
+- A light/lab theme alongside the dark one.
+- Image / text / time-series support beyond tabular.
+
+## License
+
+MIT

firstlook-0.1.0/src/firstlook.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+src/firstlook/__init__.py
+src/firstlook/baseline.py
+src/firstlook/detect.py
+src/firstlook/recommend.py
+src/firstlook/report.py
+src/firstlook/theme.py
+src/firstlook/visualize.py
+src/firstlook.egg-info/PKG-INFO
+src/firstlook.egg-info/SOURCES.txt
+src/firstlook.egg-info/dependency_links.txt
+src/firstlook.egg-info/requires.txt
+src/firstlook.egg-info/top_level.txt
+tests/test_baseline.py
+tests/test_detect.py
+tests/test_ds_fixes.py
+tests/test_recommend.py

firstlook-0.1.0/src/firstlook.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

firstlook-0.1.0/src/firstlook.egg-info/requires.txt

@@ -0,0 +1,10 @@
+pandas>=1.5
+numpy>=1.23
+plotly>=5.0
+
+[dev]
+pytest>=7
+scikit-learn>=1.1
+
+[fit]
+scikit-learn>=1.1

firstlook-0.1.0/src/firstlook.egg-info/top_level.txt

@@ -0,0 +1 @@
+firstlook

firstlook-0.1.0/tests/test_baseline.py

@@ -0,0 +1,51 @@
+import numpy as np
+import pandas as pd
+
+from firstlook import fit_baseline, play
+
+
+def test_regression_baseline_scores():
+    rng = np.random.default_rng(0)
+    x = rng.normal(size=200)
+    df = pd.DataFrame({"x": x, "y": 3 * x + rng.normal(scale=0.1, size=200)})
+    b = fit_baseline(df, "y", "regression")
+    assert b.model == "LinearRegression"
+    assert b.metric == "R2"
+    assert b.score > 0.9  # near-perfect linear relationship
+
+
+def test_classification_baseline_scores():
+    rng = np.random.default_rng(1)
+    a = pd.DataFrame({"f": rng.normal(0, 1, 100), "y": 0})
+    b = pd.DataFrame({"f": rng.normal(5, 1, 100), "y": 1})
+    df = pd.concat([a, b], ignore_index=True)
+    res = fit_baseline(df, "y", "classification")
+    assert res.metric == "accuracy"
+    assert res.score > 0.9  # well-separated classes
+
+
+def test_handles_categoricals_and_missing():
+    rng = np.random.default_rng(2)
+    df = pd.DataFrame({
+        "num": rng.normal(size=120),
+        "cat": rng.choice(["a", "b", "c"], size=120),
+        "y": rng.integers(0, 2, size=120),
+    })
+    df.loc[3, "num"] = np.nan  # the pipeline should impute, not crash
+    res = fit_baseline(df, "y", "classification")
+    assert res.score is not None
+
+
+def test_tiny_data_is_skipped():
+    df = pd.DataFrame({"x": [1.0, 2, 3, 4], "y": [2.0, 4, 6, 8]})
+    res = fit_baseline(df, "y", "regression")
+    assert res.score is None and "few rows" in res.note
+
+
+def test_play_with_fit_attaches_baseline():
+    rng = np.random.default_rng(3)
+    x = rng.normal(size=150)
+    df = pd.DataFrame({"x": x, "y": 2 * x + 1 + rng.normal(scale=0.1, size=150)})
+    report = play(df, target="y", fit=True, show=False)
+    assert report.baseline is not None
+    assert report.baseline.score > 0.9

firstlook-0.1.0/tests/test_detect.py

@@ -0,0 +1,44 @@
+import numpy as np
+import pandas as pd
+import pytest
+
+from firstlook import detect_task
+
+
+def test_no_target_is_clustering():
+    df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+    assert detect_task(df, None) == "clustering"
+
+
+def test_string_target_is_classification():
+    df = pd.DataFrame({"x": [1, 2, 3, 4], "y": ["a", "b", "a", "b"]})
+    assert detect_task(df, "y") == "classification"
+
+
+def test_few_int_classes_is_classification():
+    df = pd.DataFrame({"x": np.arange(150), "y": ([0, 1, 2] * 50)})
+    assert detect_task(df, "y") == "classification"
+
+
+def test_continuous_target_is_regression():
+    rng = np.random.default_rng(0)
+    df = pd.DataFrame({"x": rng.normal(size=200), "y": rng.normal(size=200)})
+    assert detect_task(df, "y") == "regression"
+
+
+def test_small_regression_not_mistaken_for_classification():
+    # 7 distinct values in 7 rows — the trap. Ratio check must keep it regression.
+    df = pd.DataFrame({"weight": [2.4, 2.8, 3.0, 3.2, 3.6, 4.0, 4.4],
+                       "mpg": [24, 22, 20, 19, 17, 15, 14]})
+    assert detect_task(df, "mpg") == "regression"
+
+
+def test_bool_target_is_classification():
+    df = pd.DataFrame({"x": [1, 2, 3, 4], "y": [True, False, True, False]})
+    assert detect_task(df, "y") == "classification"
+
+
+def test_missing_target_raises():
+    df = pd.DataFrame({"x": [1, 2, 3]})
+    with pytest.raises(KeyError):
+        detect_task(df, "nope")

firstlook-0.1.0/tests/test_ds_fixes.py

@@ -0,0 +1,40 @@
+"""Regression tests for the data-science review fixes."""
+import numpy as np
+import pandas as pd
+
+from firstlook import detect_task, fit_baseline
+from firstlook.visualize import _rank_features
+
+
+def test_binary_float_target_is_classification():
+    # nunique == 2 is binary classification even as floats in a small frame
+    df = pd.DataFrame({"x": np.arange(30), "y": [0.0, 1.0] * 15})
+    assert detect_task(df, "y") == "classification"
+
+
+def test_imbalanced_classification_uses_balanced_accuracy():
+    rng = np.random.default_rng(5)
+    n = 400
+    df = pd.DataFrame({"f": rng.normal(size=n), "y": rng.choice([0, 1], size=n, p=[0.9, 0.1])})
+    res = fit_baseline(df, "y", "classification")
+    assert res.metric == "balanced accuracy"  # not plain accuracy on imbalanced data
+
+
+def test_balanced_classification_uses_plain_accuracy():
+    rng = np.random.default_rng(6)
+    df = pd.DataFrame({"f": rng.normal(size=200), "y": rng.choice([0, 1], size=200)})
+    res = fit_baseline(df, "y", "classification")
+    assert res.metric == "accuracy"
+
+
+def test_classification_ranks_separating_feature_first():
+    # 'sep' separates the classes; 'noise' doesn't. Correlation-ratio ranking
+    # must surface 'sep' (Pearson-on-label-codes would not, reliably).
+    rng = np.random.default_rng(7)
+    df = pd.DataFrame({
+        "noise": rng.normal(0, 1, 200),
+        "sep": np.concatenate([rng.normal(0, 1, 100), rng.normal(6, 1, 100)]),
+        "y": np.array([0] * 100 + [1] * 100),
+    })
+    ranked = _rank_features(df, "y", ["noise", "sep"], "classification")
+    assert ranked[0] == "sep"

firstlook-0.1.0/tests/test_recommend.py

@@ -0,0 +1,38 @@
+import numpy as np
+import pandas as pd
+
+from firstlook import recommend, visualize
+
+
+def test_regression_starts_linear():
+    df = pd.DataFrame({"x": np.arange(100), "y": np.arange(100) * 2.0 + 1})
+    rec = recommend(df, "y")
+    assert rec.task == "regression"
+    assert rec.start == "LinearRegression"
+    assert rec.models
+
+
+def test_classification_flags_imbalance_and_categorical():
+    rng = np.random.default_rng(0)
+    df = pd.DataFrame({
+        "amt": rng.exponential(size=300),
+        "region": rng.choice(["NA", "EU"], size=300),
+        "fraud": rng.choice([0, 1], size=300, p=[0.92, 0.08]),
+    })
+    rec = recommend(df, "fraud")
+    assert rec.task == "classification"
+    joined = " ".join(rec.notes).lower()
+    assert "imbalanced" in joined
+    assert "categorical" in joined
+
+
+def test_missing_values_flagged():
+    df = pd.DataFrame({"x": [1.0, np.nan, 3.0, 4.0] * 20, "y": np.arange(80) * 1.0})
+    rec = recommend(df, "y")
+    assert any("missing" in n.lower() for n in rec.notes)
+
+
+def test_visualize_returns_figure():
+    df = pd.DataFrame({"a": np.arange(60) * 1.0, "b": np.arange(60) * 1.5, "y": ([0, 1] * 30)})
+    fig = visualize(df, "y")
+    assert fig.data  # at least one trace