pbidriver 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pbidriver-0.1.0/LICENSE +21 -0
- pbidriver-0.1.0/PKG-INFO +232 -0
- pbidriver-0.1.0/README.md +182 -0
- pbidriver-0.1.0/pbidriver/__init__.py +8 -0
- pbidriver-0.1.0/pbidriver/__main__.py +6 -0
- pbidriver-0.1.0/pbidriver/bridge.py +378 -0
- pbidriver-0.1.0/pbidriver/cli.py +2321 -0
- pbidriver-0.1.0/pbidriver/definition.py +292 -0
- pbidriver-0.1.0/pbidriver.egg-info/PKG-INFO +232 -0
- pbidriver-0.1.0/pbidriver.egg-info/SOURCES.txt +16 -0
- pbidriver-0.1.0/pbidriver.egg-info/dependency_links.txt +1 -0
- pbidriver-0.1.0/pbidriver.egg-info/entry_points.txt +2 -0
- pbidriver-0.1.0/pbidriver.egg-info/requires.txt +7 -0
- pbidriver-0.1.0/pbidriver.egg-info/top_level.txt +1 -0
- pbidriver-0.1.0/pyproject.toml +49 -0
- pbidriver-0.1.0/setup.cfg +4 -0
- pbidriver-0.1.0/tests/test_cli.py +84 -0
- pbidriver-0.1.0/tests/test_definition.py +132 -0
pbidriver-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jerome Eliezer
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
pbidriver-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pbidriver
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: WebDriver for Power BI Desktop: let AI agents see and drive it (screenshots, visual data, dialogs, slicers, DAX, Performance Analyzer).
|
|
5
|
+
Author: Jerome Eliezer
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2026 Jerome Eliezer
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://github.com/speak2jerome/pbidriver
|
|
29
|
+
Project-URL: Issues, https://github.com/speak2jerome/pbidriver/issues
|
|
30
|
+
Project-URL: Changelog, https://github.com/speak2jerome/pbidriver/blob/main/CHANGELOG.md
|
|
31
|
+
Keywords: power bi,power bi desktop,screenshot,ai agents,webview2,devtools,dax,automation
|
|
32
|
+
Classifier: Development Status :: 4 - Beta
|
|
33
|
+
Classifier: Environment :: Console
|
|
34
|
+
Classifier: Intended Audience :: Developers
|
|
35
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
36
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
37
|
+
Classifier: Programming Language :: Python :: 3
|
|
38
|
+
Classifier: Topic :: Software Development :: Testing
|
|
39
|
+
Classifier: Topic :: Office/Business
|
|
40
|
+
Requires-Python: >=3.9
|
|
41
|
+
Description-Content-Type: text/markdown
|
|
42
|
+
License-File: LICENSE
|
|
43
|
+
Requires-Dist: playwright>=1.40
|
|
44
|
+
Requires-Dist: psutil>=5.9
|
|
45
|
+
Requires-Dist: pywin32>=306
|
|
46
|
+
Requires-Dist: pillow>=10.0
|
|
47
|
+
Provides-Extra: test
|
|
48
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
49
|
+
Dynamic: license-file
|
|
50
|
+
|
|
51
|
+
# pbidriver
|
|
52
|
+
|
|
53
|
+
**WebDriver for Power BI Desktop.** Let AI agents see and drive Power BI Desktop: screenshots of pages, visuals and every view, the data behind visuals, blocking dialogs, slicers, tooltips, menus, bookmarks, DAX and Performance Analyzer. It all runs locally against Power BI Desktop, with no screen grabs and no publishing to the service.
|
|
54
|
+
|
|
55
|
+
(Not a data connector or ODBC driver: "driver" as in WebDriver, the thing that drives an app for automation.)
|
|
56
|
+
|
|
57
|
+
Every command is a CLI call that prints one JSON object, so any agent that can run a shell command can use it: Claude Code, Codex, GitHub Copilot, Cursor or your own scripts.
|
|
58
|
+
|
|
59
|
+
```powershell
|
|
60
|
+
pbidriver launch "C:\reports\Sales.pbix"
|
|
61
|
+
pbidriver shot --page "Overview" --annotate # PNG of the canvas, each visual labelled with its index
|
|
62
|
+
pbidriver read --page "Overview" # chart points, card values, table/matrix cells, slicer state
|
|
63
|
+
pbidriver slicer --visual "Region" --select "West" --shot
|
|
64
|
+
pbidriver dax "EVALUATE TOPN(5, Sales)"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Why
|
|
68
|
+
|
|
69
|
+
Agents can already write DAX and edit PBIP files, but they can't see the result. Screenshots of the whole desktop are noisy and need focus. Publishing to see a report breaks the fast loop. `pbidriver` closes that gap:
|
|
70
|
+
|
|
71
|
+
- **See:** pixel-exact PNGs of the canvas, one visual, every visual, the full UI, or the Table / Model / DAX query / TMDL views. It handles canvases bigger than the window, minimized windows, and windows behind other windows.
|
|
72
|
+
- **Read:** the values behind visuals, as Power BI formats them: chart data points, cards, whole tables and matrices (virtualized grids are scrolled through), and slicer options with their selection.
|
|
73
|
+
- **Never get stuck:** blocking dialogs of all three kinds Power BI uses (in-app, native Windows, and legacy Internet Explorer) are detected on every call, can be read and captured, and are answered with `dialog --click`. Input is refused while a modal is open. Broken visuals ("Can't display this visual") are reported.
|
|
74
|
+
- **Interact:** real mouse and keyboard input, so visuals react exactly as if you clicked: slicers, clicks, scrolling (including sideways in wide tables), typing, keys, tooltips, context and "More options" menus (sort, drill, show as table…), and bookmarks.
|
|
75
|
+
- **Understand:** every page, visual, field, filter and bookmark read from the report file, plus the model's tables, columns, measures (with DAX) and relationships.
|
|
76
|
+
- **Measure:** Performance Analyzer timings per visual (DAX query / visual display / other), optionally with each visual's DAX query.
|
|
77
|
+
- **Close the loop:** reload a PBIP after edits on disk, save, and close (answering the save prompt).
|
|
78
|
+
|
|
79
|
+
## Requirements
|
|
80
|
+
|
|
81
|
+
- Windows 10 or 11, with Power BI Desktop (Microsoft Store or installer build).
|
|
82
|
+
- Python 3.9+.
|
|
83
|
+
- Optional, for page captures and reloads on any open window: Microsoft's **Desktop Bridge**, in Power BI Desktop June 2026 or later. It's on by default (Options > Security > "Enable external tool access to Power BI Desktop through secure local APIs").
|
|
84
|
+
|
|
85
|
+
## Install
|
|
86
|
+
|
|
87
|
+
```powershell
|
|
88
|
+
pip install pbidriver
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The latest code from GitHub: `pip install git+https://github.com/speak2jerome/pbidriver`. From a checkout: `pip install .` (or `pip install -r requirements.txt` and run `python -m pbidriver`).
|
|
92
|
+
|
|
93
|
+
Playwright is used only to attach to Power BI's own WebView2, so `playwright install` is **not** needed.
|
|
94
|
+
|
|
95
|
+
## Two ways to connect
|
|
96
|
+
|
|
97
|
+
| | Started with `pbidriver launch` | Any open Power BI Desktop |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| How | DevTools on a private WebView2 profile, so it works next to your other Power BI windows | Microsoft's Desktop Bridge, the local model engine, and Windows itself |
|
|
100
|
+
| Page and visual screenshots | ✅ live state, any zoom, all views | ✅ report pages and visuals (positions from the saved file) |
|
|
101
|
+
| Table / Model / DAX / TMDL view screenshots | ✅ | ❌ |
|
|
102
|
+
| Read visual data, hover, menus, slicers, click, scroll, type | ✅ | ❌ |
|
|
103
|
+
| Dialogs | ✅ all kinds | ✅ native and legacy (in-app ones need `launch`) |
|
|
104
|
+
| `inventory`, `dax`, `model`, `reload`, `close`, `status` | ✅ | ✅ |
|
|
105
|
+
|
|
106
|
+
Use `pbidriver instances` to list every running Power BI with its pid, file, DevTools port and Bridge status. Pick one with `--pid`.
|
|
107
|
+
|
|
108
|
+
## Commands
|
|
109
|
+
|
|
110
|
+
Every command prints `{"ok": true, ...}` or `{"ok": false, "error": "..."}`. Commands that touch the UI also return `alerts` whenever something needs attention.
|
|
111
|
+
|
|
112
|
+
**Instances and state**
|
|
113
|
+
|
|
114
|
+
| Command | What it does |
|
|
115
|
+
|---|---|
|
|
116
|
+
| `launch FILE` | Opens a `.pbix`, `.pbip` or `.pbit` in its own Power BI with DevTools on `--port` (default 9333). Reports startup prompts, such as "Enable script visuals" or file recovery. |
|
|
117
|
+
| `instances` | Lists every running Power BI Desktop: pid, window, file, DevTools port, Bridge, model port, unsaved changes. |
|
|
118
|
+
| `status` | Current page, views, unsaved changes, alerts. |
|
|
119
|
+
| `pages` / `alerts [--all-views]` | Report pages; dialogs, banners and broken visuals right now. |
|
|
120
|
+
|
|
121
|
+
**Look**
|
|
122
|
+
|
|
123
|
+
| Command | What it does |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `shot [--page P]` | Captures the report canvas. Add `--visual V` for one visual, `--all-visuals` for one PNG per visual, or `--full` for the whole UI. |
|
|
126
|
+
| `shot --view table\|model\|dax\|tmdl` | Captures another view without switching to it. |
|
|
127
|
+
| `shot --annotate` | Draws each visual's index and type on the capture, so you can say "visual 18". |
|
|
128
|
+
| `shot --scale 2` | Real 2× detail, re-rendered rather than upscaled. |
|
|
129
|
+
| `shot --bridge` | Captures through the Desktop Bridge. This happens automatically when the instance has no DevTools. |
|
|
130
|
+
| `visuals [--page P] [--all-pages]` | Live list of visuals: index, type, title, box, text, error. |
|
|
131
|
+
|
|
132
|
+
**Read**
|
|
133
|
+
|
|
134
|
+
| Command | What it does |
|
|
135
|
+
|---|---|
|
|
136
|
+
| `read [--page P] [--visual V] [--max-rows N]` | The data behind visuals: `points` (charts), `card`, `grid` (tables and matrices, scrolled through), `slicer`, `text`. |
|
|
137
|
+
| `inventory [--file F] [--summary] [--type T]` | Every page, visual, field, filter and bookmark from the report file, with no clicking (`.pbix`, `.pbit`, `.pbip`, PBIR or legacy layout). |
|
|
138
|
+
| `model [--part tables\|columns\|measures\|relationships]` | The semantic model, including measure DAX. |
|
|
139
|
+
| `dax "EVALUATE ..." [--file q.dax] [--max-rows N]` | Runs a DAX query against the open model. |
|
|
140
|
+
| `perf [--page P] [--queries]` | Performance Analyzer: per-visual total, DAX query, visual display and other time in ms, optionally with each visual's query. |
|
|
141
|
+
|
|
142
|
+
**Interact** (all accept `--page`, `--view`, `--shot`, `--force`)
|
|
143
|
+
|
|
144
|
+
| Command | What it does |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `slicer --visual V --select A B \| --clear` | Sets exactly this selection, in list or dropdown slicers, including long virtualized lists. With no flag it lists the options. |
|
|
147
|
+
| `click [--visual V] [--text T \| --at X,Y] [--ctrl --shift --double --right]` | Clicks by text or accessible name, or at a point (fractions 0–1 or px) inside a visual. |
|
|
148
|
+
| `hover [--visual V] [--text T \| --at X,Y]` | Hovers a point and returns the tooltip rows. |
|
|
149
|
+
| `menu [--visual V] [--text T \| --at X,Y \| --more] [--choose "A > B"]` | Right-click or "More options" menu: lists the items, or chooses one (e.g. `--choose "Sort by > Total Sales"`). |
|
|
150
|
+
| `scroll [--visual V \| --view table] --dx N --dy N` | Mouse-wheel scrolling. In table visuals, every 120 px of `--dx` moves one column. |
|
|
151
|
+
| `type TEXT [--visual V] [--into T] [--press Enter]` / `key KEY...` | Typing (e.g. into a search slicer) and key presses (`Control+A`, `Escape`, `PageDown`). |
|
|
152
|
+
| `bookmarks [--apply NAME]` | Lists bookmarks, or applies one. |
|
|
153
|
+
| `wait --text T [--gone]` | Waits until text appears or disappears. |
|
|
154
|
+
|
|
155
|
+
**Dialogs, file and lifecycle**
|
|
156
|
+
|
|
157
|
+
| Command | What it does |
|
|
158
|
+
|---|---|
|
|
159
|
+
| `dialog` / `dialog --shot` / `dialog --click BUTTON` | Reads, captures or answers the blocking dialog. |
|
|
160
|
+
| `reload [--report-only]` | Reloads a PBIP/PBIR report (and model) from disk after an agent edited the files (Desktop Bridge). |
|
|
161
|
+
| `save` | Saves the report; the Desktop Bridge confirms there are no unsaved changes left. |
|
|
162
|
+
| `close [--discard \| --save]` | Closes a Power BI window and answers the "save your changes?" prompt. |
|
|
163
|
+
|
|
164
|
+
Common options: `--port` (default `9333`, env `PBIDRIVER_PORT`), `--pid`, `--settle` (max seconds to wait for rendering, default 20). Captures go to `./pbidriver_shots/` unless you pass `--out`.
|
|
165
|
+
|
|
166
|
+
## Agent instructions (paste into CLAUDE.md / AGENTS.md)
|
|
167
|
+
|
|
168
|
+
```
|
|
169
|
+
Power BI Desktop is driven with the `pbidriver` CLI; every call prints JSON.
|
|
170
|
+
- Start: `pbidriver status`; if nothing is running, `pbidriver launch "<report.pbix|.pbip>"`.
|
|
171
|
+
- Look: `pbidriver shot --page "<page>" --annotate`, then open the PNG at `file`. Visual indices in the
|
|
172
|
+
picture work as `--visual <index>` everywhere.
|
|
173
|
+
- Numbers: `pbidriver read --page "<page>"` (all visuals) or `read --visual <index>`; `pbidriver dax "EVALUATE ..."`.
|
|
174
|
+
- Every result may contain "alerts". If alerts.blocked is true, read the dialog with `pbidriver dialog`
|
|
175
|
+
and answer it with `pbidriver dialog --click "<button>"`. Fix alerts.visual_errors before moving on.
|
|
176
|
+
- Structure: `pbidriver inventory --summary`; measures and their DAX: `pbidriver model --part measures`.
|
|
177
|
+
- After editing PBIP files on disk: `pbidriver reload`, then `shot` again.
|
|
178
|
+
- Interact: `slicer --visual "<name>" --select "<value>" --shot`, `scroll --visual <index> --dx 1200`,
|
|
179
|
+
`hover --visual <index> --text "<value>"`, `menu --visual <index> --more --choose "Sort by > <field>"`.
|
|
180
|
+
- Performance: `pbidriver perf --page "<page>"`.
|
|
181
|
+
- When done: `pbidriver save` if the changes should be kept, then `pbidriver close --discard`.
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## How it works
|
|
185
|
+
|
|
186
|
+
- **DevTools.** Power BI Desktop draws its UI in WebView2 (Chromium) pages, one per view. `launch` sets `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=<port>` and a private `WEBVIEW2_USER_DATA_FOLDER`. The private folder gives the instance its own browser process, so the flag applies even while other Power BI windows are open. `pbidriver` attaches with Playwright's `connect_over_cdp`.
|
|
187
|
+
- **Pixel-exact captures.** Only the target's rectangle is captured (`Page.captureScreenshot` with a clip), so panes and scrollbars never leak in. If the canvas doesn't fit the window, the viewport is emulated larger for the capture and then restored. Power BI resets script-driven scrolling, so scrolling isn't an option. WebView2 stops painting while minimized, so the window is restored without focus and put back exactly as it was. Captures wait for the canvas to stop changing.
|
|
188
|
+
- **Data.** Built-in visuals bind each data point to its element (`__data__`) with `tooltipInfo`: the field names and values exactly as Power BI formats them. Tables and matrices are read cell by cell through their ARIA grid roles. They are virtualized, so `read` scrolls them one axis at a time; Power BI moves one column per horizontal wheel event.
|
|
189
|
+
- **Dialogs.** Power BI uses three technologies. In-app dialogs are read from the DOM. Native WinForms dialogs are read from their child windows and clicked with `BM_CLICK`. Legacy Internet Explorer dialogs (the "Do you want to save your changes?" prompt, "Enable script visuals", "Create table") are read and clicked through the dialog's own HTML via `WM_HTML_GETOBJECT`. While a modal is open, the main window is disabled; every command reports this as `alerts.blocked`, and input commands refuse to run, because input sent through DevTools would go around the modal.
|
|
190
|
+
- **Desktop Bridge.** Microsoft's local JSON-RPC API on the named pipe `pbi-desktop-bridge-<pid>`, used for page and region snapshots, reload and unsaved state.
|
|
191
|
+
- **DAX.** Windows PowerShell loads the ADOMD.NET client that ships inside Power BI Desktop and queries the local model engine (`msmdsrv`). Nothing extra is installed.
|
|
192
|
+
|
|
193
|
+
## Security and privacy
|
|
194
|
+
|
|
195
|
+
- `launch` opens a DevTools port on `127.0.0.1`. While that instance runs, any program on your machine could drive it, including your signed-in Power BI session. Close it when you're done (`pbidriver close`).
|
|
196
|
+
- Everything stays on your machine. Screenshots and data are written to local files; what your agent does with them is up to the agent.
|
|
197
|
+
- `perf --queries` reads queries through the clipboard. It restores your clipboard text afterwards, but non-text clipboard content is lost.
|
|
198
|
+
|
|
199
|
+
## Limits
|
|
200
|
+
|
|
201
|
+
- The DOM selectors are Power BI internals. They're tested on Power BI Desktop 2.152 (March 2026) and 2.159 (November 2026), both Store builds. A monthly update can rename them; they're grouped at the top of `pbidriver/cli.py`.
|
|
202
|
+
- Ribbon features (`perf`, `bookmarks`) look for English labels.
|
|
203
|
+
- Custom visuals render in sandboxed iframes. They can be captured and clicked (`--at`), but their data can't be read; use `dax` with the fields from `inventory`.
|
|
204
|
+
- `read` on large tables returns the rows Power BI has loaded (it loads them in windows of about 500). Use `dax` for every row.
|
|
205
|
+
- Slicer commands rescan the list after each click: about 10 s on a 28-option list.
|
|
206
|
+
- Bridge captures locate visuals from the saved file, so unsaved layout changes may be off. `reload` works for PBIP/PBIR projects only; reloading the model needs a recent model compatibility level.
|
|
207
|
+
- `error_text` for broken visuals matches known error phrases, so it's a heuristic.
|
|
208
|
+
|
|
209
|
+
## Related projects
|
|
210
|
+
|
|
211
|
+
- [Microsoft Power BI Desktop Bridge](https://learn.microsoft.com/en-us/power-bi/developer/agentic/power-bi-desktop-bridge-overview) and its `powerbi-desktop` CLI: Microsoft's official local API (status, open, reload, page snapshots). `pbidriver` uses it where it's available.
|
|
212
|
+
- [Power BI Modeling MCP server](https://github.com/microsoft/powerbi-modeling-mcp): Microsoft's MCP server for semantic model changes.
|
|
213
|
+
- [pbi-webview2](https://glama.ai/mcp/servers/bibiibjorn/pbi-webview2): an earlier MCP server that drives Power BI Desktop over the same WebView2 DevTools route.
|
|
214
|
+
- [sulaiman013/powerbi-mcp](https://github.com/sulaiman013/powerbi-mcp): an MCP server with model tools and Desktop Bridge screenshots.
|
|
215
|
+
- [PBI Inspector](https://github.com/NatVanG/PBI-Inspector): rule-based testing of report definitions.
|
|
216
|
+
|
|
217
|
+
## Development
|
|
218
|
+
|
|
219
|
+
```powershell
|
|
220
|
+
pip install -e .[test]
|
|
221
|
+
pytest
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
The tests use synthetic report files and need no Power BI. For live checks, `launch` a copy of a report and run the commands above.
|
|
225
|
+
|
|
226
|
+
## Author
|
|
227
|
+
|
|
228
|
+
Jerome Eliezer ([speak2jerome](https://github.com/speak2jerome))
|
|
229
|
+
|
|
230
|
+
## License
|
|
231
|
+
|
|
232
|
+
MIT, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# pbidriver
|
|
2
|
+
|
|
3
|
+
**WebDriver for Power BI Desktop.** Let AI agents see and drive Power BI Desktop: screenshots of pages, visuals and every view, the data behind visuals, blocking dialogs, slicers, tooltips, menus, bookmarks, DAX and Performance Analyzer. It all runs locally against Power BI Desktop, with no screen grabs and no publishing to the service.
|
|
4
|
+
|
|
5
|
+
(Not a data connector or ODBC driver: "driver" as in WebDriver, the thing that drives an app for automation.)
|
|
6
|
+
|
|
7
|
+
Every command is a CLI call that prints one JSON object, so any agent that can run a shell command can use it: Claude Code, Codex, GitHub Copilot, Cursor or your own scripts.
|
|
8
|
+
|
|
9
|
+
```powershell
|
|
10
|
+
pbidriver launch "C:\reports\Sales.pbix"
|
|
11
|
+
pbidriver shot --page "Overview" --annotate # PNG of the canvas, each visual labelled with its index
|
|
12
|
+
pbidriver read --page "Overview" # chart points, card values, table/matrix cells, slicer state
|
|
13
|
+
pbidriver slicer --visual "Region" --select "West" --shot
|
|
14
|
+
pbidriver dax "EVALUATE TOPN(5, Sales)"
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Why
|
|
18
|
+
|
|
19
|
+
Agents can already write DAX and edit PBIP files, but they can't see the result. Screenshots of the whole desktop are noisy and need focus. Publishing to see a report breaks the fast loop. `pbidriver` closes that gap:
|
|
20
|
+
|
|
21
|
+
- **See:** pixel-exact PNGs of the canvas, one visual, every visual, the full UI, or the Table / Model / DAX query / TMDL views. It handles canvases bigger than the window, minimized windows, and windows behind other windows.
|
|
22
|
+
- **Read:** the values behind visuals, as Power BI formats them: chart data points, cards, whole tables and matrices (virtualized grids are scrolled through), and slicer options with their selection.
|
|
23
|
+
- **Never get stuck:** blocking dialogs of all three kinds Power BI uses (in-app, native Windows, and legacy Internet Explorer) are detected on every call, can be read and captured, and are answered with `dialog --click`. Input is refused while a modal is open. Broken visuals ("Can't display this visual") are reported.
|
|
24
|
+
- **Interact:** real mouse and keyboard input, so visuals react exactly as if you clicked: slicers, clicks, scrolling (including sideways in wide tables), typing, keys, tooltips, context and "More options" menus (sort, drill, show as table…), and bookmarks.
|
|
25
|
+
- **Understand:** every page, visual, field, filter and bookmark read from the report file, plus the model's tables, columns, measures (with DAX) and relationships.
|
|
26
|
+
- **Measure:** Performance Analyzer timings per visual (DAX query / visual display / other), optionally with each visual's DAX query.
|
|
27
|
+
- **Close the loop:** reload a PBIP after edits on disk, save, and close (answering the save prompt).
|
|
28
|
+
|
|
29
|
+
## Requirements
|
|
30
|
+
|
|
31
|
+
- Windows 10 or 11, with Power BI Desktop (Microsoft Store or installer build).
|
|
32
|
+
- Python 3.9+.
|
|
33
|
+
- Optional, for page captures and reloads on any open window: Microsoft's **Desktop Bridge**, in Power BI Desktop June 2026 or later. It's on by default (Options > Security > "Enable external tool access to Power BI Desktop through secure local APIs").
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
```powershell
|
|
38
|
+
pip install pbidriver
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The latest code from GitHub: `pip install git+https://github.com/speak2jerome/pbidriver`. From a checkout: `pip install .` (or `pip install -r requirements.txt` and run `python -m pbidriver`).
|
|
42
|
+
|
|
43
|
+
Playwright is used only to attach to Power BI's own WebView2, so `playwright install` is **not** needed.
|
|
44
|
+
|
|
45
|
+
## Two ways to connect
|
|
46
|
+
|
|
47
|
+
| | Started with `pbidriver launch` | Any open Power BI Desktop |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| How | DevTools on a private WebView2 profile, so it works next to your other Power BI windows | Microsoft's Desktop Bridge, the local model engine, and Windows itself |
|
|
50
|
+
| Page and visual screenshots | ✅ live state, any zoom, all views | ✅ report pages and visuals (positions from the saved file) |
|
|
51
|
+
| Table / Model / DAX / TMDL view screenshots | ✅ | ❌ |
|
|
52
|
+
| Read visual data, hover, menus, slicers, click, scroll, type | ✅ | ❌ |
|
|
53
|
+
| Dialogs | ✅ all kinds | ✅ native and legacy (in-app ones need `launch`) |
|
|
54
|
+
| `inventory`, `dax`, `model`, `reload`, `close`, `status` | ✅ | ✅ |
|
|
55
|
+
|
|
56
|
+
Use `pbidriver instances` to list every running Power BI with its pid, file, DevTools port and Bridge status. Pick one with `--pid`.
|
|
57
|
+
|
|
58
|
+
## Commands
|
|
59
|
+
|
|
60
|
+
Every command prints `{"ok": true, ...}` or `{"ok": false, "error": "..."}`. Commands that touch the UI also return `alerts` whenever something needs attention.
|
|
61
|
+
|
|
62
|
+
**Instances and state**
|
|
63
|
+
|
|
64
|
+
| Command | What it does |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `launch FILE` | Opens a `.pbix`, `.pbip` or `.pbit` in its own Power BI with DevTools on `--port` (default 9333). Reports startup prompts, such as "Enable script visuals" or file recovery. |
|
|
67
|
+
| `instances` | Lists every running Power BI Desktop: pid, window, file, DevTools port, Bridge, model port, unsaved changes. |
|
|
68
|
+
| `status` | Current page, views, unsaved changes, alerts. |
|
|
69
|
+
| `pages` / `alerts [--all-views]` | Report pages; dialogs, banners and broken visuals right now. |
|
|
70
|
+
|
|
71
|
+
**Look**
|
|
72
|
+
|
|
73
|
+
| Command | What it does |
|
|
74
|
+
|---|---|
|
|
75
|
+
| `shot [--page P]` | Captures the report canvas. Add `--visual V` for one visual, `--all-visuals` for one PNG per visual, or `--full` for the whole UI. |
|
|
76
|
+
| `shot --view table\|model\|dax\|tmdl` | Captures another view without switching to it. |
|
|
77
|
+
| `shot --annotate` | Draws each visual's index and type on the capture, so you can say "visual 18". |
|
|
78
|
+
| `shot --scale 2` | Real 2× detail, re-rendered rather than upscaled. |
|
|
79
|
+
| `shot --bridge` | Captures through the Desktop Bridge. This happens automatically when the instance has no DevTools. |
|
|
80
|
+
| `visuals [--page P] [--all-pages]` | Live list of visuals: index, type, title, box, text, error. |
|
|
81
|
+
|
|
82
|
+
**Read**
|
|
83
|
+
|
|
84
|
+
| Command | What it does |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `read [--page P] [--visual V] [--max-rows N]` | The data behind visuals: `points` (charts), `card`, `grid` (tables and matrices, scrolled through), `slicer`, `text`. |
|
|
87
|
+
| `inventory [--file F] [--summary] [--type T]` | Every page, visual, field, filter and bookmark from the report file, with no clicking (`.pbix`, `.pbit`, `.pbip`, PBIR or legacy layout). |
|
|
88
|
+
| `model [--part tables\|columns\|measures\|relationships]` | The semantic model, including measure DAX. |
|
|
89
|
+
| `dax "EVALUATE ..." [--file q.dax] [--max-rows N]` | Runs a DAX query against the open model. |
|
|
90
|
+
| `perf [--page P] [--queries]` | Performance Analyzer: per-visual total, DAX query, visual display and other time in ms, optionally with each visual's query. |
|
|
91
|
+
|
|
92
|
+
**Interact** (all accept `--page`, `--view`, `--shot`, `--force`)
|
|
93
|
+
|
|
94
|
+
| Command | What it does |
|
|
95
|
+
|---|---|
|
|
96
|
+
| `slicer --visual V --select A B \| --clear` | Sets exactly this selection, in list or dropdown slicers, including long virtualized lists. With no flag it lists the options. |
|
|
97
|
+
| `click [--visual V] [--text T \| --at X,Y] [--ctrl --shift --double --right]` | Clicks by text or accessible name, or at a point (fractions 0–1 or px) inside a visual. |
|
|
98
|
+
| `hover [--visual V] [--text T \| --at X,Y]` | Hovers a point and returns the tooltip rows. |
|
|
99
|
+
| `menu [--visual V] [--text T \| --at X,Y \| --more] [--choose "A > B"]` | Right-click or "More options" menu: lists the items, or chooses one (e.g. `--choose "Sort by > Total Sales"`). |
|
|
100
|
+
| `scroll [--visual V \| --view table] --dx N --dy N` | Mouse-wheel scrolling. In table visuals, every 120 px of `--dx` moves one column. |
|
|
101
|
+
| `type TEXT [--visual V] [--into T] [--press Enter]` / `key KEY...` | Typing (e.g. into a search slicer) and key presses (`Control+A`, `Escape`, `PageDown`). |
|
|
102
|
+
| `bookmarks [--apply NAME]` | Lists bookmarks, or applies one. |
|
|
103
|
+
| `wait --text T [--gone]` | Waits until text appears or disappears. |
|
|
104
|
+
|
|
105
|
+
**Dialogs, file and lifecycle**
|
|
106
|
+
|
|
107
|
+
| Command | What it does |
|
|
108
|
+
|---|---|
|
|
109
|
+
| `dialog` / `dialog --shot` / `dialog --click BUTTON` | Reads, captures or answers the blocking dialog. |
|
|
110
|
+
| `reload [--report-only]` | Reloads a PBIP/PBIR report (and model) from disk after an agent edited the files (Desktop Bridge). |
|
|
111
|
+
| `save` | Saves the report; the Desktop Bridge confirms there are no unsaved changes left. |
|
|
112
|
+
| `close [--discard \| --save]` | Closes a Power BI window and answers the "save your changes?" prompt. |
|
|
113
|
+
|
|
114
|
+
Common options: `--port` (default `9333`, env `PBIDRIVER_PORT`), `--pid`, `--settle` (max seconds to wait for rendering, default 20). Captures go to `./pbidriver_shots/` unless you pass `--out`.
|
|
115
|
+
|
|
116
|
+
## Agent instructions (paste into CLAUDE.md / AGENTS.md)
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
Power BI Desktop is driven with the `pbidriver` CLI; every call prints JSON.
|
|
120
|
+
- Start: `pbidriver status`; if nothing is running, `pbidriver launch "<report.pbix|.pbip>"`.
|
|
121
|
+
- Look: `pbidriver shot --page "<page>" --annotate`, then open the PNG at `file`. Visual indices in the
|
|
122
|
+
picture work as `--visual <index>` everywhere.
|
|
123
|
+
- Numbers: `pbidriver read --page "<page>"` (all visuals) or `read --visual <index>`; `pbidriver dax "EVALUATE ..."`.
|
|
124
|
+
- Every result may contain "alerts". If alerts.blocked is true, read the dialog with `pbidriver dialog`
|
|
125
|
+
and answer it with `pbidriver dialog --click "<button>"`. Fix alerts.visual_errors before moving on.
|
|
126
|
+
- Structure: `pbidriver inventory --summary`; measures and their DAX: `pbidriver model --part measures`.
|
|
127
|
+
- After editing PBIP files on disk: `pbidriver reload`, then `shot` again.
|
|
128
|
+
- Interact: `slicer --visual "<name>" --select "<value>" --shot`, `scroll --visual <index> --dx 1200`,
|
|
129
|
+
`hover --visual <index> --text "<value>"`, `menu --visual <index> --more --choose "Sort by > <field>"`.
|
|
130
|
+
- Performance: `pbidriver perf --page "<page>"`.
|
|
131
|
+
- When done: `pbidriver save` if the changes should be kept, then `pbidriver close --discard`.
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## How it works
|
|
135
|
+
|
|
136
|
+
- **DevTools.** Power BI Desktop draws its UI in WebView2 (Chromium) pages, one per view. `launch` sets `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=<port>` and a private `WEBVIEW2_USER_DATA_FOLDER`. The private folder gives the instance its own browser process, so the flag applies even while other Power BI windows are open. `pbidriver` attaches with Playwright's `connect_over_cdp`.
|
|
137
|
+
- **Pixel-exact captures.** Only the target's rectangle is captured (`Page.captureScreenshot` with a clip), so panes and scrollbars never leak in. If the canvas doesn't fit the window, the viewport is emulated larger for the capture and then restored. Power BI resets script-driven scrolling, so scrolling isn't an option. WebView2 stops painting while minimized, so the window is restored without focus and put back exactly as it was. Captures wait for the canvas to stop changing.
|
|
138
|
+
- **Data.** Built-in visuals bind each data point to its element (`__data__`) with `tooltipInfo`: the field names and values exactly as Power BI formats them. Tables and matrices are read cell by cell through their ARIA grid roles. They are virtualized, so `read` scrolls them one axis at a time; Power BI moves one column per horizontal wheel event.
|
|
139
|
+
- **Dialogs.** Power BI uses three technologies. In-app dialogs are read from the DOM. Native WinForms dialogs are read from their child windows and clicked with `BM_CLICK`. Legacy Internet Explorer dialogs (the "Do you want to save your changes?" prompt, "Enable script visuals", "Create table") are read and clicked through the dialog's own HTML via `WM_HTML_GETOBJECT`. While a modal is open, the main window is disabled; every command reports this as `alerts.blocked`, and input commands refuse to run, because input sent through DevTools would go around the modal.
|
|
140
|
+
- **Desktop Bridge.** Microsoft's local JSON-RPC API on the named pipe `pbi-desktop-bridge-<pid>`, used for page and region snapshots, reload and unsaved state.
|
|
141
|
+
- **DAX.** Windows PowerShell loads the ADOMD.NET client that ships inside Power BI Desktop and queries the local model engine (`msmdsrv`). Nothing extra is installed.
|
|
142
|
+
|
|
143
|
+
## Security and privacy
|
|
144
|
+
|
|
145
|
+
- `launch` opens a DevTools port on `127.0.0.1`. While that instance runs, any program on your machine could drive it, including your signed-in Power BI session. Close it when you're done (`pbidriver close`).
|
|
146
|
+
- Everything stays on your machine. Screenshots and data are written to local files; what your agent does with them is up to the agent.
|
|
147
|
+
- `perf --queries` reads queries through the clipboard. It restores your clipboard text afterwards, but non-text clipboard content is lost.
|
|
148
|
+
|
|
149
|
+
## Limits
|
|
150
|
+
|
|
151
|
+
- The DOM selectors are Power BI internals. They're tested on Power BI Desktop 2.152 (March 2026) and 2.159 (November 2026), both Store builds. A monthly update can rename them; they're grouped at the top of `pbidriver/cli.py`.
|
|
152
|
+
- Ribbon features (`perf`, `bookmarks`) look for English labels.
|
|
153
|
+
- Custom visuals render in sandboxed iframes. They can be captured and clicked (`--at`), but their data can't be read; use `dax` with the fields from `inventory`.
|
|
154
|
+
- `read` on large tables returns the rows Power BI has loaded (it loads them in windows of about 500). Use `dax` for every row.
|
|
155
|
+
- Slicer commands rescan the list after each click: about 10 s on a 28-option list.
|
|
156
|
+
- Bridge captures locate visuals from the saved file, so unsaved layout changes may be off. `reload` works for PBIP/PBIR projects only; reloading the model needs a recent model compatibility level.
|
|
157
|
+
- `error_text` for broken visuals matches known error phrases, so it's a heuristic.
|
|
158
|
+
|
|
159
|
+
## Related projects
|
|
160
|
+
|
|
161
|
+
- [Microsoft Power BI Desktop Bridge](https://learn.microsoft.com/en-us/power-bi/developer/agentic/power-bi-desktop-bridge-overview) and its `powerbi-desktop` CLI: Microsoft's official local API (status, open, reload, page snapshots). `pbidriver` uses it where it's available.
|
|
162
|
+
- [Power BI Modeling MCP server](https://github.com/microsoft/powerbi-modeling-mcp): Microsoft's MCP server for semantic model changes.
|
|
163
|
+
- [pbi-webview2](https://glama.ai/mcp/servers/bibiibjorn/pbi-webview2): an earlier MCP server that drives Power BI Desktop over the same WebView2 DevTools route.
|
|
164
|
+
- [sulaiman013/powerbi-mcp](https://github.com/sulaiman013/powerbi-mcp): an MCP server with model tools and Desktop Bridge screenshots.
|
|
165
|
+
- [PBI Inspector](https://github.com/NatVanG/PBI-Inspector): rule-based testing of report definitions.
|
|
166
|
+
|
|
167
|
+
## Development
|
|
168
|
+
|
|
169
|
+
```powershell
|
|
170
|
+
pip install -e .[test]
|
|
171
|
+
pytest
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The tests use synthetic report files and need no Power BI. For live checks, `launch` a copy of a report and run the commands above.
|
|
175
|
+
|
|
176
|
+
## Author
|
|
177
|
+
|
|
178
|
+
Jerome Eliezer ([speak2jerome](https://github.com/speak2jerome))
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
MIT, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"""pbidriver: WebDriver for Power BI Desktop. Lets AI agents see and drive it.
|
|
2
|
+
|
|
3
|
+
The command line lives in pbidriver.cli; pbidriver.bridge talks to Microsoft's Desktop Bridge and
|
|
4
|
+
the local model, and pbidriver.definition reads report files.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
__version__ = "0.1.0"
|
|
8
|
+
__author__ = "Jerome Eliezer"
|