pbigen 0.1.0__py3-none-any.whl

pbigen/__init__.py

@@ -0,0 +1,39 @@
+"""pbigen — generate world-class Power BI dashboards from any data source.
+
+Point it at a table (BigQuery, Snowflake, Redshift, Synapse/Fabric, Databricks, ClickHouse,
+Athena, a Parquet/Iceberg/Delta lake on GCS/S3/ADLS, or a Cube semantic layer), and it
+introspects the schema, reasons about the data shape, and writes an openable Power BI project:
+a navigation sidebar, data-appropriate charts and filters, and usage notes.
+
+    import pbigen
+
+    result = pbigen.generate(
+        "bigquery",
+        source_config={"project": "my-proj", "dataset": "sales", "table": "orders"},
+        objective="Revenue and orders by region over time",
+        theme="midnight",
+        out_dir="out",
+    )
+    print(result.pbip_path)
+
+The design defaults to a deterministic, no-key engine. Pass ``model="gpt-4o-mini"`` (or any
+LiteLLM model id, hosted or local) to let a language model refine the design; only metadata is
+ever sent to it.
+
+Author: Arka Gupta
+"""
+from __future__ import annotations
+
+from .core.generator import GenerateResult, generate
+from .sources import available_kinds, get_source
+from .themes import available_themes, get_theme
+
+__version__ = "0.1.0"
+__author__ = "Arka Gupta"
+
+__all__ = [
+    "generate", "GenerateResult",
+    "get_source", "available_kinds",
+    "get_theme", "available_themes",
+    "__version__",
+]

pbigen/cli.py

@@ -0,0 +1,114 @@
+"""Command-line interface.
+
+    pbigen generate --source bigquery --set project=p dataset=d table=t --theme midnight
+    pbigen sources                       # list available source kinds
+    pbigen themes                        # list built-in themes
+    pbigen test --source lakehouse --set uri=data.parquet fmt=parquet
+
+Config values are passed as ``key=value`` pairs after ``--set`` and forwarded to the adapter.
+Integers and booleans are coerced; everything else stays a string.
+
+Author: Arka Gupta
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from . import __version__
+from .sources import available_kinds, get_source
+from .themes import available_themes
+
+
+def _coerce(value: str) -> Any:
+    low = value.lower()
+    if low in ("true", "false"):
+        return low == "true"
+    if value.isdigit():
+        return int(value)
+    return value
+
+
+def _parse_set(pairs: list[str]) -> dict:
+    cfg: dict[str, Any] = {}
+    for pair in pairs or []:
+        if "=" not in pair:
+            raise SystemExit(f"--set expects key=value, got {pair!r}")
+        key, _, value = pair.partition("=")
+        cfg[key.strip()] = _coerce(value.strip())
+    return cfg
+
+
+def _cmd_generate(args: argparse.Namespace) -> int:
+    from .core.generator import generate
+    cfg = _parse_set(args.set)
+    result = generate(
+        args.source,
+        out_dir=args.out,
+        name=args.name,
+        objective=args.objective or "",
+        model=args.model,
+        theme=args.theme,
+        source_config=cfg,
+    )
+    print(f"Generated {result.n_pages} pages from {result.table} "
+          f"({result.n_columns} columns) using {result.model_name}.")
+    print(f"Open: {result.pbip_path}")
+    return 0
+
+
+def _cmd_sources(_: argparse.Namespace) -> int:
+    print("Available sources:")
+    for kind in available_kinds():
+        print(f"  - {kind}")
+    return 0
+
+
+def _cmd_themes(_: argparse.Namespace) -> int:
+    print("Built-in themes (or pass a path to your own Power BI theme JSON):")
+    for name in available_themes():
+        print(f"  - {name}")
+    return 0
+
+
+def _cmd_test(args: argparse.Namespace) -> int:
+    src = get_source(args.source, **_parse_set(args.set))
+    result = src.test_connection()
+    print(result.message)
+    return 0 if result.ok else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="pbigen",
+                                description="Generate Power BI dashboards from any data source.")
+    p.add_argument("--version", action="version", version=f"pbigen {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    g = sub.add_parser("generate", help="generate a Power BI project from a source")
+    g.add_argument("--source", required=True, help=f"source kind ({', '.join(available_kinds())})")
+    g.add_argument("--set", nargs="*", default=[], help="source config as key=value pairs")
+    g.add_argument("--objective", help="what the dashboard should answer")
+    g.add_argument("--model", help="LiteLLM model id (omit for the deterministic design)")
+    g.add_argument("--theme", help="built-in theme name or path to a Power BI theme JSON")
+    g.add_argument("--out", default="out", help="output directory (default: out)")
+    g.add_argument("--name", help="project name (default: derived from the table)")
+    g.set_defaults(func=_cmd_generate)
+
+    t = sub.add_parser("test", help="test connectivity + introspection for a source")
+    t.add_argument("--source", required=True)
+    t.add_argument("--set", nargs="*", default=[])
+    t.set_defaults(func=_cmd_test)
+
+    sub.add_parser("sources", help="list available source kinds").set_defaults(func=_cmd_sources)
+    sub.add_parser("themes", help="list built-in themes").set_defaults(func=_cmd_themes)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv if argv is not None else sys.argv[1:])
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pbigen/core/__init__.py

@@ -0,0 +1,18 @@
+"""Core: the platform-neutral brain — canonical schema, design rules, layout, generator.
+
+Nothing in ``core`` imports a database driver or a cloud SDK, so the design logic is fully
+testable on its own and portable across every source and emitter.
+
+Author: Arka Gupta
+"""
+from __future__ import annotations
+
+from .design import Design, Measure, Page, Visual, classify, design, propose_measures
+from .generator import GenerateResult, generate
+from .layout import pack
+from .schema import Column, Schema
+
+__all__ = [
+    "Column", "Schema", "Measure", "Visual", "Page", "Design",
+    "classify", "propose_measures", "design", "pack", "generate", "GenerateResult",
+]

pbigen/core/design.py

@@ -0,0 +1,184 @@
+"""The design brain: turn a schema + an objective into a logical dashboard design.
+
+This module is deliberately deterministic and dependency-free. It classifies every column
+(measure / date / category / geo / id), proposes sensible measures, and lays out a narrative
+set of pages whose chart and filter choices are driven by the *data shape* (types and
+distinct-value counts). A language model can refine this design (see ``blueprint``), but the
+rules here always produce a complete, coherent dashboard on their own.
+
+Author: Arka Gupta
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .schema import DATETIME, NUMERIC_TYPES, Schema
+
+# ---- column-role heuristics -------------------------------------------------
+_DATE_HINT = re.compile(r"(date|dttm|_dt$|_ts$|timestamp|period|year_?month|yyyymm|mth|month|year|week|day)", re.I)
+_ID_HINT = re.compile(r"(_id$|^id$|_key$|^key$|uuid|guid|_no$|_number$|_code$|ssn|tax_?id|passport|phone|email|account)", re.I)
+_CAT_HINT = re.compile(r"(type|status|category|categ|segment|brand|region|area|zone|state|country|city|class|mode|method|group|flag|channel|source|reason|gender|department|company|product|service|tier|band|level)", re.I)
+_GEO_HINT = re.compile(r"(lat|lon|lng|postal|zipcode|geohash)", re.I)
+_MONEY_HINT = re.compile(r"(income|cost|amount|amt|revenue|sales|price|fee|charge|value|gmv|spend|profit|margin|billing|payment)", re.I)
+# columns that are derived parts of a date — redundant as filters once a real date exists
+_PERIOD_PART = re.compile(r"(year|month|week|quarter|day.?of|_dt$|period|_yr$)", re.I)
+
+
+@dataclass
+class Measure:
+    """A logical measure: an aggregation of a column, or a ratio/share of other measures.
+
+    The emitter turns these into the target BI expression (e.g. DAX for Power BI)."""
+
+    name: str
+    kind: str = "agg"            # agg | ratio | share
+    column: str | None = None
+    agg: str = "SUM"             # SUM | AVERAGE | MIN | MAX | COUNT | DISTINCTCOUNT
+    numerator: str | None = None
+    denominator: str | None = None
+    dimension: str | None = None
+    money: bool = False
+    percent: bool = False
+
+
+@dataclass
+class Visual:
+    """One visual on a page. Fields not relevant to a type are simply left unset."""
+
+    type: str                    # card|kpi|line|area|column|columnStacked|bar|barStacked|
+    #                              donut|pie|scatter|table|matrix|slicer
+    title: str = ""
+    measures: list[str] = field(default_factory=list)
+    category: str | None = None
+    series: str | None = None
+    columns: list[str] = field(default_factory=list)
+    x_measure: str | None = None
+    y_measure: str | None = None
+    size_measure: str | None = None
+    slicer_mode: str = "Dropdown"
+    # layout (filled by the layout packer)
+    x: int = 0
+    y: int = 0
+    w: int = 0
+    h: int = 0
+    z: int = 0
+
+
+@dataclass
+class Page:
+    name: str
+    visuals: list[Visual] = field(default_factory=list)
+    slicers: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Design:
+    measures: list[Measure] = field(default_factory=list)
+    pages: list[Page] = field(default_factory=list)
+    usage_notes: list[str] = field(default_factory=list)
+    rationale: str = ""
+
+
+def classify(schema: Schema) -> dict[str, list[str]]:
+    """Bucket columns into measures / dates / categories / geo / ids."""
+    out: dict[str, list[str]] = {"measures": [], "dates": [], "categories": [], "geo": [], "ids": []}
+    for c in schema.columns:
+        low = c.name.lower()
+        if _GEO_HINT.search(low):
+            out["geo"].append(c.name)
+        elif c.dtype == DATETIME or (_DATE_HINT.search(low) and (c.is_numeric or c.dtype == "string" or c.is_temporal)):
+            out["dates"].append(c.name)
+        elif _ID_HINT.search(low):
+            out["ids"].append(c.name)
+        elif c.dtype in NUMERIC_TYPES:
+            out["measures"].append(c.name)
+        else:
+            out["categories"].append(c.name)
+    out["categories"].sort(key=lambda n: (0 if _CAT_HINT.search(n.lower()) else 1, len(n)))
+    out["dates"].sort(key=lambda n: (0 if _DATE_HINT.search(n.lower()) else 1, len(n)))
+    return out
+
+
+def propose_measures(schema: Schema, limit: int = 6) -> list[Measure]:
+    """Synthesise SUM measures from numeric columns when none are supplied."""
+    cls = classify(schema)
+    out: list[Measure] = []
+    for col in cls["measures"][:limit]:
+        pretty = "Total " + col.replace("_", " ").title()
+        out.append(Measure(pretty, "agg", column=col, agg="SUM", money=bool(_MONEY_HINT.search(col.lower()))))
+    return out
+
+
+def _good_slicer(name: str, schema: Schema, real_dates: set[str]) -> bool:
+    if name in real_dates:
+        return True
+    if real_dates and _PERIOD_PART.search(name):          # redundant with the date range
+        return False
+    col = schema.by_name(name)
+    card = col.cardinality if col else None
+    return card is None or card <= 50                     # dropdowns only for low-cardinality
+
+
+def design(schema: Schema, objective: str = "", measures: list[Measure] | None = None) -> Design:
+    """Deterministic, cardinality-aware dashboard design (the always-on baseline)."""
+    cls = classify(schema)
+    real_dates = {c.name for c in schema.columns if c.dtype == DATETIME}
+    measures = measures or propose_measures(schema)
+    headline = [m.name for m in measures][:6] or ["(no measure)"]
+    lead = headline[0]
+
+    date = cls["dates"][0] if cls["dates"] else None
+    dims = [d for d in cls["categories"]][:4]
+    dim0 = dims[0] if dims else None
+    dim1 = dims[1] if len(dims) > 1 else None
+
+    def low_card(col: str | None) -> bool:
+        c = schema.by_name(col) if col else None
+        return bool(col) and (c is None or c.cardinality is None or c.cardinality <= 8)
+
+    def breakdown(metric: str, dim: str, title: str) -> Visual:
+        # donut only for few categories, else a bar chart
+        return Visual("donut" if low_card(dim) else "bar", title, measures=[metric], category=dim)
+
+    slicers = [s for s in ([date] if date else []) + dims if _good_slicer(s, schema, real_dates)][:5]
+    pages: list[Page] = []
+
+    # 1) Executive Summary
+    v = [Visual("card", m, measures=[m]) for m in headline[:4]]
+    if date:
+        v.append(Visual("line", f"{lead} over time", measures=headline[:2], category=date))
+    if dim0:
+        v.append(breakdown(lead, dim0, f"{lead} by {dim0}"))
+    if dim1:
+        v.append(breakdown(lead, dim1, f"{lead} by {dim1}"))
+    pages.append(Page("Executive Summary", v, slicers))
+
+    # 2) Trends over time
+    if date:
+        v = [Visual("card", m, measures=[m]) for m in headline[:3]]
+        v.append(Visual("line", f"{lead} trend", measures=headline[:3], category=date))
+        if dim0:
+            v.append(Visual("column", f"{lead} by {dim0}", measures=headline[:2], category=dim0, series=dim1))
+        pages.append(Page("Trends Over Time", v, slicers))
+
+    # 3) Segmentation & drivers
+    if dim0:
+        v = [Visual("column", f"{lead} by {dim0}", measures=[lead], category=dim0)]
+        if dim1:
+            v.append(Visual("bar", f"{lead} by {dim1}", measures=[lead], category=dim1))
+        v.append(Visual("matrix", f"{dim0} × measures", measures=headline, category=dim0, series=dim1))
+        pages.append(Page("Segmentation & Drivers", v, slicers))
+
+    # 4) Detail / self-serve
+    detail_cols = ([date] if date else []) + dims
+    v = [Visual("table", "Detail (all fields)", measures=headline, columns=detail_cols)]
+    pages.append(Page("Detailed Data", v, slicers))
+
+    notes = [
+        "Use the filters on the left to focus the report (date range, then segment by the dropdowns).",
+        "KPI cards show headline totals; charts show trends and breakdowns; tables show the detail.",
+        "Move across the page tabs for the summary, trends, segmentation and detail.",
+    ]
+    return Design(measures=measures, pages=pages, usage_notes=notes,
+                  rationale="Deterministic, cardinality-aware design.")

pbigen/core/generator.py

@@ -0,0 +1,69 @@
+"""The generator: source -> schema+cardinality -> design -> Power BI project.
+
+This is the one function that stitches the pieces together. It stays thin on purpose — all the
+judgement lives in the source adapters, the design model and the emitter — so the pipeline is easy
+to read and to test end to end.
+
+Author: Arka Gupta
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..models import Model, get_model
+from ..sources import Source, get_source
+from ..themes import get_theme, split_chrome
+from .design import Design
+
+
+@dataclass
+class GenerateResult:
+    pbip_path: str
+    design: Design
+    table: str
+    n_columns: int
+    n_pages: int
+    model_name: str
+
+
+def _project_name(raw: str) -> str:
+    name = re.sub(r"[^0-9A-Za-z_-]+", "-", raw).strip("-")
+    return name or "dashboard"
+
+
+def generate(
+    source: Source | str,
+    *,
+    out_dir: str = "out",
+    name: str | None = None,
+    objective: str = "",
+    model: Model | str | None = None,
+    theme: str | None = None,
+    source_config: dict | None = None,
+    model_config: dict | None = None,
+) -> GenerateResult:
+    """Generate a Power BI project from a source.
+
+    ``source`` may be a configured :class:`Source` or a kind string (with ``source_config``).
+    ``model`` may be a :class:`Model`, a LiteLLM model id, or ``None`` for the deterministic design.
+    ``theme`` may be a built-in name or a path to a Power BI theme JSON.
+    """
+    src = source if isinstance(source, Source) else get_source(source, **(source_config or {}))
+    mdl = model if isinstance(model, Model) else get_model(model, **(model_config or {}))
+
+    schema = src.schema_with_cardinality()
+    design = mdl.design(schema, objective)
+    theme_doc, sidebar, accent = split_chrome(get_theme(theme))
+
+    from ..emit import write_project
+    project = name or _project_name(schema.display_name or schema.table)
+    pbip_path = write_project(
+        design, schema, src.power_query(), out_dir, project,
+        theme=theme_doc, sidebar_color=sidebar, accent=accent,
+        brand=schema.display_name,
+    )
+    return GenerateResult(
+        pbip_path=pbip_path, design=design, table=schema.table,
+        n_columns=len(schema.columns), n_pages=len(design.pages), model_name=mdl.name,
+    )

pbigen/core/layout.py

@@ -0,0 +1,88 @@
+"""Layout packer: place a page's visuals on a wide canvas with a left filter sidebar.
+
+The design brain decides *what* each page shows; this module decides *where*, reliably:
+a left sidebar for the logo + stacked filters + a "how to use" note, and a main area with a
+KPI card row and charts/tables packed by footprint (wide pivots full-width, narrow ones paired).
+
+Author: Arka Gupta
+"""
+from __future__ import annotations
+
+from .design import Page, Visual
+from .schema import DATETIME, Schema
+
+# canvas + sidebar geometry (a large canvas so dense layouts are not clipped)
+PAGE_W, PAGE_H = 1920, 1080
+SIDEBAR_W = 300
+LOGO_ZONE_H = 200
+TITLE_H = 84
+CARD_H = 128
+GAP = 16
+MARGIN = 20
+
+
+def _is_wide(v: Visual) -> bool:
+    """A visual that shows many columns needs the full width."""
+    if v.type == "matrix":
+        return bool(v.series) or len(v.measures) >= 3
+    if v.type == "table":
+        return len(v.columns) + len(v.measures) >= 6
+    return False
+
+
+def pack(page: Page, schema: Schema) -> list[Visual]:
+    """Return the page's visuals with x/y/w/h assigned, plus positioned slicer visuals."""
+    real_dates = {c.name for c in schema.columns if c.dtype == DATETIME}
+    placed: list[Visual] = []
+
+    # slicers stacked in the sidebar; real dates render as a range slider
+    sy = LOGO_ZONE_H
+    for col in page.slicers[:7]:
+        is_date = col in real_dates
+        h = 84 if is_date else 72
+        placed.append(Visual("slicer", title=col, category=col,
+                             slicer_mode="Between" if is_date else "Dropdown",
+                             x=20, y=sy, w=SIDEBAR_W - 40, h=h))
+        sy += h + 12
+
+    mx0 = SIDEBAR_W + MARGIN
+    mw = PAGE_W - mx0 - MARGIN
+    bottom = PAGE_H - MARGIN
+
+    cards = [v for v in page.visuals if v.type in ("card", "kpi")][:8]
+    body = [v for v in page.visuals if v.type not in ("card", "kpi")]
+
+    y = MARGIN + TITLE_H
+    if cards:
+        per = 4 if len(cards) > 3 else len(cards)
+        for i0 in range(0, len(cards), per):
+            row = cards[i0:i0 + per]
+            n = len(row)
+            w = (mw - (n - 1) * GAP) // n
+            for i, v in enumerate(row):
+                v.x, v.y, v.w, v.h = mx0 + i * (w + GAP), y, w, CARD_H
+                placed.append(v)
+            y += CARD_H + GAP
+
+    wide = [v for v in body if _is_wide(v)]
+    charts = [v for v in body if not _is_wide(v) and v.type not in ("table", "matrix")]
+    ntables = [v for v in body if not _is_wide(v) and v.type in ("table", "matrix")]
+    pairable: list[Visual] = []                # interleave so a narrow table pairs with a chart
+    while charts or ntables:
+        if charts:
+            pairable.append(charts.pop(0))
+        if ntables:
+            pairable.append(ntables.pop(0))
+    rows = [[wv] for wv in wide] + [pairable[i:i + 2] for i in range(0, len(pairable), 2)]
+
+    n = max(1, len(rows))
+    row_h = (bottom - y - (n - 1) * GAP) // n
+    for r in rows:
+        x = mx0
+        widths = [mw] if len(r) == 1 else [(mw - GAP) // 2] * 2
+        for w, v in zip(widths, r):
+            v.x, v.y, v.w, v.h = x, y, w, row_h
+            placed.append(v)
+            x += w + GAP
+        y += row_h + GAP
+    return placed

pbigen/core/schema.py

@@ -0,0 +1,64 @@
+"""Canonical, source-agnostic schema types.
+
+Every data source adapter normalises its native metadata into these types, so the design
+engine and the Power BI emitter never need to know which warehouse the data came from.
+
+Author: Arka Gupta
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Canonical data-type vocabulary. Adapters map their native types onto these; the design
+# engine reasons in these terms and the emitter maps them to the target BI model types.
+STRING = "string"
+INTEGER = "integer"
+FLOAT = "float"
+DECIMAL = "decimal"
+BOOLEAN = "boolean"
+DATE = "date"
+DATETIME = "datetime"
+TIME = "time"
+
+NUMERIC_TYPES = frozenset({INTEGER, FLOAT, DECIMAL})
+TEMPORAL_TYPES = frozenset({DATE, DATETIME, TIME})
+
+
+@dataclass(frozen=True)
+class Column:
+    """A single column of a table/view, in canonical terms."""
+
+    name: str
+    dtype: str = STRING
+    #: approximate distinct-value count, when the source could cheaply provide it
+    cardinality: int | None = None
+
+    @property
+    def is_numeric(self) -> bool:
+        return self.dtype in NUMERIC_TYPES
+
+    @property
+    def is_temporal(self) -> bool:
+        return self.dtype in TEMPORAL_TYPES
+
+
+@dataclass
+class Schema:
+    """The shape of a table/view plus a human label used for titles."""
+
+    table: str
+    columns: list[Column] = field(default_factory=list)
+    display_name: str | None = None
+
+    def names(self) -> list[str]:
+        return [c.name for c in self.columns]
+
+    def by_name(self, name: str) -> Column | None:
+        return next((c for c in self.columns if c.name == name), None)
+
+    def with_cardinality(self, counts: dict[str, int]) -> Schema:
+        """Return a copy with distinct-value counts merged onto matching columns."""
+        cols = [
+            Column(c.name, c.dtype, counts.get(c.name, c.cardinality)) for c in self.columns
+        ]
+        return Schema(self.table, cols, self.display_name)

pbigen/emit/__init__.py

@@ -0,0 +1,12 @@
+"""Emitters — turn a design into on-disk BI artifacts.
+
+Today: Power BI (PBIP/PBIR report + TMDL semantic model). The seam is deliberately narrow
+(``write_project``) so other targets can be added without touching the design brain.
+
+Author: Arka Gupta
+"""
+from __future__ import annotations
+
+from .pbir import write_project
+
+__all__ = ["write_project"]