pbi-enterprise-cli 0.1.0.dev0__py3-none-any.whl

pbi_cli/intelligence/visual_builder.py

@@ -0,0 +1,429 @@
+"""Build Power BI PBIR GA visual JSON blobs.
+
+Schema reference:
+  visualContainer: https://developer.microsoft.com/json-schemas/fabric/item/
+                   report/definition/visualContainer/2.7.0/schema.json
+  visualConfiguration (embedded inside "visual" key):
+    - visualType, query, objects, visualContainerObjects
+  query.queryState:
+    - keys are visual-role names (e.g. Category, Y, Values)
+    - each role has a "projections" array
+    - each projection: { "field": <QueryExpressionContainer>, "queryRef": str }
+  Field expressions:
+    - Measure:     {"Measure":     {"Expression": {"SourceRef": {"Entity": tbl}}, "Property": prop}}
+    - Column:      {"Column":      {"Expression": {"SourceRef": {"Entity": tbl}}, "Property": prop}}
+    - Aggregation: {"Aggregation": {"Expression": {"Column": {...}}, "Function": 0}}
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+AGG_SUM = 0
+AGG_AVG = 1
+AGG_MIN = 2
+AGG_MAX = 3
+AGG_COUNT = 4
+AGG_NAMES = {AGG_SUM: "Sum", AGG_AVG: "Avg", AGG_MIN: "Min", AGG_MAX: "Max", AGG_COUNT: "Count"}
+
+VISUAL_CONTAINER_SCHEMA = (
+    "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/"
+    "visualContainer/2.7.0/schema.json"
+)
+
+
+@dataclass
+class FieldDef:
+    """One field to bind to a visual role slot."""
+
+    entity: str  # table name, e.g. "financials"
+    property: str  # column or measure name, e.g. "Sales"
+    is_measure: bool = False  # True = explicit DAX measure
+    agg: int | None = AGG_SUM  # None = no aggregation (plain column)
+
+    @property  # type: ignore[operator]
+    def query_ref(self) -> str:
+        """Unique queryRef string for this field within a visual."""
+        if self.is_measure or self.agg is None:
+            return f"{self.entity}.{self.property}"
+        agg_name = AGG_NAMES.get(self.agg, "Sum")
+        return f"{agg_name}({self.entity}[{self.property}])"
+
+    def to_field_expr(self) -> dict[str, Any]:
+        """Build the QueryExpressionContainer for this field."""
+        src = {"SourceRef": {"Entity": self.entity}}
+        if self.is_measure:
+            return {"Measure": {"Expression": src, "Property": self.property}}
+        if self.agg is None:
+            return {"Column": {"Expression": src, "Property": self.property}}
+        return {
+            "Aggregation": {
+                "Expression": {"Column": {"Expression": src, "Property": self.property}},
+                "Function": self.agg,
+            }
+        }
+
+    def to_projection(self) -> dict[str, Any]:
+        """Build a projection entry for query.queryState.{role}.projections."""
+        return {"field": self.to_field_expr(), "queryRef": self.query_ref}
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+def _query_state(roles: dict[str, list[FieldDef]]) -> dict[str, Any]:
+    """Build query.queryState from a role-name → FieldDef list mapping."""
+    return {
+        role: {"projections": [f.to_projection() for f in fields]}
+        for role, fields in roles.items()
+        if fields
+    }
+
+
+# ── Visual body builders ───────────────────────────────────────────────────────
+
+
+def build_card(value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "card",
+        "query": {"queryState": _query_state({"Values": [value]})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_bar_chart(category: FieldDef, value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "barChart",
+        "query": {"queryState": _query_state({"Category": [category], "Y": [value]})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_column_chart(category: FieldDef, value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "columnChart",
+        "query": {"queryState": _query_state({"Category": [category], "Y": [value]})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_line_chart(axis: FieldDef, value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "lineChart",
+        "query": {"queryState": _query_state({"Category": [axis], "Y": [value]})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_slicer(value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "slicer",
+        "query": {"queryState": _query_state({"Values": [value]})},
+        "objects": {
+            "data": [{"properties": {"mode": {"expr": {"Literal": {"Value": "'Basic'"}}}}}]
+        },
+        "visualContainerObjects": {},
+    }
+
+
+def build_table(columns: list[FieldDef]) -> dict[str, Any]:
+    return {
+        "visualType": "tableEx",
+        "query": {"queryState": _query_state({"Values": columns})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_multi_row_card(fields: list[FieldDef]) -> dict[str, Any]:
+    return {
+        "visualType": "multiRowCard",
+        "query": {"queryState": _query_state({"Values": fields})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_scatter_chart(
+    x_axis: FieldDef,
+    y_axis: FieldDef,
+    details: FieldDef | None = None,
+    size: FieldDef | None = None,
+) -> dict[str, Any]:
+    roles: dict[str, list[FieldDef]] = {"X": [x_axis], "Y": [y_axis]}
+    if details:
+        roles["Details"] = [details]
+    if size:
+        roles["Size"] = [size]
+    return {
+        "visualType": "scatterChart",
+        "query": {"queryState": _query_state(roles)},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_gauge(
+    value: FieldDef,
+    target: FieldDef | None = None,
+    min_val: FieldDef | None = None,
+    max_val: FieldDef | None = None,
+) -> dict[str, Any]:
+    roles: dict[str, list[FieldDef]] = {"Y": [value]}
+    if target:
+        roles["TargetValue"] = [target]
+    if min_val:
+        roles["MinValue"] = [min_val]
+    if max_val:
+        roles["MaxValue"] = [max_val]
+    return {
+        "visualType": "gauge",
+        "query": {"queryState": _query_state(roles)},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_donut_chart(category: FieldDef, value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "donutChart",
+        "query": {"queryState": _query_state({"Category": [category], "Y": [value]})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_pie_chart(category: FieldDef, value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "pieChart",
+        "query": {"queryState": _query_state({"Category": [category], "Y": [value]})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_treemap(group: FieldDef, value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "treemap",
+        "query": {"queryState": _query_state({"Group": [group], "Values": [value]})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_funnel(category: FieldDef, value: FieldDef) -> dict[str, Any]:
+    return {
+        "visualType": "funnel",
+        "query": {"queryState": _query_state({"Category": [category], "Y": [value]})},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_waterfall(
+    category: FieldDef, value: FieldDef, breakdown: FieldDef | None = None
+) -> dict[str, Any]:
+    roles: dict[str, list[FieldDef]] = {"Category": [category], "Y": [value]}
+    if breakdown:
+        roles["Breakdown"] = [breakdown]
+    return {
+        "visualType": "waterfallChart",
+        "query": {"queryState": _query_state(roles)},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_matrix(
+    rows: list[FieldDef], values: list[FieldDef], columns: list[FieldDef] | None = None
+) -> dict[str, Any]:
+    roles: dict[str, list[FieldDef]] = {"Rows": rows, "Values": values}
+    if columns:
+        roles["Columns"] = columns
+    return {
+        "visualType": "pivotTable",
+        "query": {"queryState": _query_state(roles)},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+def build_ribbon_chart(
+    category: FieldDef, value: FieldDef, series: FieldDef | None = None
+) -> dict[str, Any]:
+    roles: dict[str, list[FieldDef]] = {"Category": [category], "Y": [value]}
+    if series:
+        roles["Series"] = [series]
+    return {
+        "visualType": "ribbonChart",
+        "query": {"queryState": _query_state(roles)},
+        "objects": {},
+        "visualContainerObjects": {},
+    }
+
+
+# ── VisualSpec and serialisation ───────────────────────────────────────────────
+
+
+@dataclass
+class VisualSpec:
+    visual_type: str
+    visual_body: dict[str, Any]
+    x: int = 0
+    y: int = 0
+    width: int = 300
+    height: int = 200
+    tab_order: int = 0
+    name: str = field(default_factory=_new_id)
+    title: str = ""
+
+
+def spec_to_pbir_visual(spec: VisualSpec) -> dict[str, Any]:
+    """Produce the visual.json dict for PBIR GA format."""
+    body = dict(spec.visual_body)  # shallow copy
+
+    if spec.title:
+        body.setdefault("visualContainerObjects", {})
+        body["visualContainerObjects"]["title"] = [
+            {
+                "properties": {
+                    "show": {"expr": {"Literal": {"Value": "true"}}},
+                    "text": {"expr": {"Literal": {"Value": f"'{spec.title}'"}}},
+                }
+            }
+        ]
+
+    return {
+        "$schema": VISUAL_CONTAINER_SCHEMA,
+        "name": spec.name,
+        "position": {
+            "x": spec.x,
+            "y": spec.y,
+            "z": 0,
+            "width": spec.width,
+            "height": spec.height,
+            "tabOrder": spec.tab_order,
+        },
+        "visual": body,
+    }
+
+
+def spec_to_old_pbip_container(spec: VisualSpec) -> dict[str, Any]:
+    """Produce a visualContainer for old single-file PBIP report.json."""
+    import json as _json
+
+    # Old format still uses projections/prototypeQuery inside singleVisual config
+    body = spec.visual_body
+    qs = body.get("query", {}).get("queryState", {})
+
+    projections: dict[str, Any] = {}
+    select_items = []
+    from_aliases: dict[str, str] = {}
+
+    for role, role_data in qs.items():
+        role_projs = []
+        for proj in role_data.get("projections", []):
+            qr = proj["queryRef"]
+            role_projs.append({"queryRef": qr})
+            fe = proj["field"]
+            select_item, alias = _field_expr_to_select(fe, from_aliases)
+            select_item["Name"] = qr
+            select_items.append(select_item)
+        projections[role] = role_projs
+
+    from_items = [
+        {"Name": alias, "Entity": entity, "Type": 0} for entity, alias in from_aliases.items()
+    ]
+
+    config = {
+        "name": spec.name,
+        "layouts": [
+            {
+                "id": 0,
+                "position": {
+                    "x": spec.x,
+                    "y": spec.y,
+                    "z": 0,
+                    "width": spec.width,
+                    "height": spec.height,
+                    "tabOrder": spec.tab_order,
+                },
+            }
+        ],
+        "singleVisual": {
+            "visualType": body.get("visualType", spec.visual_type),
+            "projections": projections,
+            "prototypeQuery": {"Version": 2, "From": from_items, "Select": select_items},
+            "columnProperties": {},
+            "objects": body.get("objects", {}),
+            "vcObjects": {},
+        },
+    }
+    if spec.title:
+        config["singleVisual"]["objects"].setdefault(  # type: ignore[index]
+            "title",
+            [
+                {
+                    "properties": {
+                        "show": {"expr": {"Literal": {"Value": "true"}}},
+                        "text": {"expr": {"Literal": {"Value": f"'{spec.title}'"}}},
+                    }
+                }
+            ],
+        )
+
+    return {
+        "x": spec.x,
+        "y": spec.y,
+        "z": 0,
+        "width": spec.width,
+        "height": spec.height,
+        "config": _json.dumps(config, separators=(",", ":")),
+        "filters": "[]",
+        "tabOrder": spec.tab_order,
+    }
+
+
+def _field_expr_to_select(
+    fe: dict[str, Any],
+    from_aliases: dict[str, str],
+) -> tuple[dict[str, Any], str]:
+    """Convert a PBIR GA field expression to an old-format SELECT item."""
+
+    def _alias(entity: str) -> str:
+        if entity not in from_aliases:
+            from_aliases[entity] = entity[0].lower() + str(len(from_aliases))
+        return from_aliases[entity]
+
+    if "Measure" in fe:
+        m = fe["Measure"]
+        entity = m["Expression"]["SourceRef"]["Entity"]
+        alias = _alias(entity)
+        src = {"SourceRef": {"Name": alias}}
+        return {"Measure": {"Expression": src, "Property": m["Property"]}}, alias
+
+    if "Column" in fe:
+        c = fe["Column"]
+        entity = c["Expression"]["SourceRef"]["Entity"]
+        alias = _alias(entity)
+        src = {"SourceRef": {"Name": alias}}
+        return {"Column": {"Expression": src, "Property": c["Property"]}}, alias
+
+    if "Aggregation" in fe:
+        a = fe["Aggregation"]
+        inner, alias = _field_expr_to_select(a["Expression"], from_aliases)
+        return {
+            "Aggregation": {
+                "Expression": inner["Column"] if "Column" in inner else inner,
+                "Function": a["Function"],
+            }
+        }, alias
+
+    return fe, ""

pbi_cli/intelligence/visual_recommender.py

@@ -0,0 +1,42 @@
+"""Recommend Power BI visual types for a given set of measures."""
+
+from __future__ import annotations
+
+VISUAL_RULES = [
+    (
+        {"revenue", "sales", "amount", "total"},
+        "Clustered Bar Chart",
+        "Good for comparing amounts across categories",
+    ),
+    ({"ytd", "yoy", "mom", "trend", "growth"}, "Line Chart", "Time series and trend analysis"),
+    ({"kpi", "target", "actual", "vs"}, "KPI Card", "Show performance against a target"),
+    ({"rate", "ratio", "%", "percent"}, "Gauge", "Proportion and completion rates"),
+    ({"region", "country", "city", "location"}, "Map", "Geographic distribution"),
+    ({"rank", "top", "bottom"}, "Bar Chart (sorted)", "Ranking visualisation"),
+]
+
+
+class VisualRecommender:
+    def recommend(self, measures: list[str]) -> list[dict]:
+        measure_text = " ".join(measures).lower()
+        recommendations = []
+        for keywords, visual_type, rationale in VISUAL_RULES:
+            if any(kw in measure_text for kw in keywords):
+                recommendations.append(
+                    {
+                        "visual": visual_type,
+                        "rationale": rationale,
+                        "matchedMeasures": [
+                            m for m in measures if any(kw in m.lower() for kw in keywords)
+                        ],
+                    }
+                )
+        if not recommendations:
+            recommendations.append(
+                {
+                    "visual": "Table",
+                    "rationale": "Default fallback for tabular data",
+                    "matchedMeasures": measures,
+                }
+            )
+        return recommendations

pbi_cli/server/__init__.py

@@ -0,0 +1 @@
+"""FastAPI server package for pbi-cli."""

pbi_cli/server/api.py

@@ -0,0 +1,185 @@
+"""FastAPI REST server — wraps all pbi-cli commands as HTTP endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+try:
+    from pathlib import Path
+
+    from fastapi import FastAPI, HTTPException
+    from fastapi.responses import FileResponse
+    from fastapi.staticfiles import StaticFiles
+
+    app = FastAPI(title="pbi-server", version="0.1.0.dev0", docs_url="/api/docs")
+
+    # ── Singleton backend ──────────────────────────────────────────────────
+    _backend: Any = None
+
+    def get_backend() -> Any:
+        global _backend
+        if _backend is None:
+            from pbi_cli.backends.tom_backend import TomBackend
+
+            _backend = TomBackend()
+        if not _backend.is_connected():
+            try:
+                _backend.connect()
+            except Exception as exc:
+                raise HTTPException(
+                    status_code=503, detail=f"Not connected to Power BI Desktop: {exc}"
+                )
+        return _backend
+
+    # ── Status ─────────────────────────────────────────────────────────────
+
+    @app.get("/api/status")
+    def status() -> dict:
+        from pbi_cli.backends.tom_backend import find_pbi_port
+
+        port = find_pbi_port()
+        if port is None:
+            return {"connected": False, "message": "No running Power BI Desktop found"}
+        try:
+            b = get_backend()
+            info = b.model_info()
+            return {
+                "connected": True,
+                "port": port,
+                "model": info["name"],
+                "compatibilityLevel": info.get("compatibilityLevel"),
+            }
+        except Exception as exc:
+            return {"connected": False, "error": str(exc)}
+
+    # ── Model ──────────────────────────────────────────────────────────────
+
+    @app.get("/api/tables")
+    def list_tables() -> list[dict]:
+        return get_backend().table_list()
+
+    @app.get("/api/columns")
+    def list_columns(table: str | None = None) -> list[dict]:
+        return get_backend().column_list(table=table)
+
+    @app.get("/api/relationships")
+    def list_relationships() -> list[dict]:
+        return get_backend().relationship_list()
+
+    # ── Measures ───────────────────────────────────────────────────────────
+
+    @app.get("/api/measures")
+    def list_measures(table: str | None = None) -> list[dict]:
+        return get_backend().measure_list(table=table)
+
+    class MeasureCreate(BaseModel):
+        table: str
+        name: str
+        expression: str
+        formatString: str = ""
+        description: str = ""
+
+    @app.post("/api/measures", status_code=201)
+    def create_measure(body: MeasureCreate) -> dict:
+        kwargs: dict[str, Any] = {}
+        if body.formatString:
+            kwargs["formatString"] = body.formatString
+        if body.description:
+            kwargs["description"] = body.description
+        try:
+            return get_backend().measure_add(body.table, body.name, body.expression, **kwargs)
+        except Exception as exc:
+            raise HTTPException(status_code=400, detail=str(exc))
+
+    class MeasureUpdate(BaseModel):
+        expression: str | None = None
+        formatString: str | None = None
+        description: str | None = None
+
+    @app.patch("/api/measures/{table}/{name}")
+    def update_measure(table: str, name: str, body: MeasureUpdate) -> dict:
+        kwargs = {k: v for k, v in body.model_dump().items() if v is not None}
+        try:
+            return get_backend().measure_update(table, name, **kwargs)
+        except KeyError:
+            raise HTTPException(status_code=404, detail=f"Measure '{name}' not found in '{table}'")
+
+    @app.delete("/api/measures/{table}/{name}", status_code=204)
+    def delete_measure(table: str, name: str) -> None:
+        try:
+            get_backend().measure_delete(table, name)
+        except KeyError:
+            raise HTTPException(status_code=404, detail=f"Measure '{name}' not found")
+
+    # ── DAX ────────────────────────────────────────────────────────────────
+
+    class DaxQuery(BaseModel):
+        expression: str
+
+    @app.post("/api/dax/query")
+    def dax_query(body: DaxQuery) -> list[dict]:
+        try:
+            return get_backend().dax_query(body.expression)
+        except Exception as exc:
+            raise HTTPException(status_code=400, detail=str(exc))
+
+    @app.post("/api/dax/validate")
+    def dax_validate(body: DaxQuery) -> dict:
+        return get_backend().dax_validate(body.expression)
+
+    # ── Governance ─────────────────────────────────────────────────────────
+
+    @app.get("/api/govern/check")
+    def govern_check() -> list[dict]:
+        from pbi_cli.governance.engine import GovernanceEngine
+
+        return GovernanceEngine(get_backend()).run_all()
+
+    @app.post("/api/govern/fix")
+    def govern_fix() -> dict:
+        from pbi_cli.governance.engine import GovernanceEngine
+
+        engine = GovernanceEngine(get_backend())
+        violations = engine.run_all()
+        fixable = [v for v in violations if v.get("autoFixable")]
+        fixed = engine.auto_fix(fixable)
+        return {"fixed": fixed}
+
+    # ── Docs ───────────────────────────────────────────────────────────────
+
+    @app.get("/api/docs/markdown", response_class=__import__("fastapi").responses.PlainTextResponse)
+    def docs_markdown() -> str:
+        from pbi_cli.docs_gen.markdown import MarkdownDocsGenerator
+
+        return MarkdownDocsGenerator(get_backend()).generate()
+
+    # ── Suggest ────────────────────────────────────────────────────────────
+
+    @app.get("/api/suggest/measures")
+    def suggest_measures() -> list[dict]:
+        b = get_backend()
+        from pbi_cli.commands.model import _build_measure_suggestions
+
+        return _build_measure_suggestions(b.table_list(), b.column_list())
+
+    @app.post("/api/suggest/visuals")
+    def suggest_visuals(body: dict) -> list[dict]:
+        from pbi_cli.intelligence.visual_recommender import VisualRecommender
+
+        measures = body.get("measures", [])
+        return VisualRecommender().recommend(measures)
+
+    # ── Static frontend ────────────────────────────────────────────────────
+
+    _static_dir = Path(__file__).parent / "static"
+    if _static_dir.exists():
+        app.mount("/static", StaticFiles(directory=str(_static_dir)), name="static")
+
+    @app.get("/", include_in_schema=False)
+    def index() -> FileResponse:
+        return FileResponse(str(_static_dir / "index.html"))
+
+except ImportError:
+    app = None  # type: ignore[assignment]