powerbi-pbip-forensics 1.0.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.
- powerbi_pbip_forensics-1.0.0/LICENSE +11 -0
- powerbi_pbip_forensics-1.0.0/PKG-INFO +573 -0
- powerbi_pbip_forensics-1.0.0/README.md +530 -0
- powerbi_pbip_forensics-1.0.0/pyproject.toml +103 -0
- powerbi_pbip_forensics-1.0.0/setup.cfg +4 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/__init__.py +5 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/__main__.py +3 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/__init__.py +1 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/audit.py +55 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/dax_rules.py +232 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/diff.py +212 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/filters.py +165 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/inventory.py +82 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/model_rules.py +212 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/performance.py +162 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/semantic.py +245 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/stage_model.py +30 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/stage_visual.py +122 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/visual_rules.py +191 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/automation.py +92 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/cli.py +305 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/discovery/__init__.py +1 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/discovery/detector.py +68 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/__init__.py +1 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/common.py +62 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_diff.py +27 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_full_audit.py +28 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_inspect.py +30 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_model_audit.py +27 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_perf_log.py +39 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_report.py +46 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_visual_deps.py +48 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/findings/__init__.py +1 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/findings/catalog.py +107 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/findings/issues.py +41 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/findings/summary.py +21 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/graph/__init__.py +1 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/graph/model_graph.py +256 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/models.py +255 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/__init__.py +1 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/dax.py +234 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/model_loader.py +147 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/pbir.py +298 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/tmdl.py +367 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/py.typed +0 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/__init__.py +1 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/html_report.py +619 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/insights.py +291 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/merge.py +60 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/render.py +260 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/security/__init__.py +1 -0
- powerbi_pbip_forensics-1.0.0/src/pbip_forensics/security/safety.py +161 -0
- powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/PKG-INFO +573 -0
- powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/SOURCES.txt +56 -0
- powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/dependency_links.txt +1 -0
- powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/entry_points.txt +2 -0
- powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/requires.txt +10 -0
- powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
Power BI PBIP Forensics
|
|
2
|
+
Copyright (c) 2026 Vinicius de Souza Santos. All rights reserved.
|
|
3
|
+
|
|
4
|
+
This software and its documentation are proprietary and confidential.
|
|
5
|
+
No license, express or implied, is granted to use, copy, modify, distribute,
|
|
6
|
+
sublicense or sell this software, except under a separate written agreement
|
|
7
|
+
with the copyright holder or under the terms of a marketplace listing
|
|
8
|
+
explicitly published by the copyright holder.
|
|
9
|
+
|
|
10
|
+
The licensing model for commercial distribution has not been decided yet.
|
|
11
|
+
See docs/licensing-options.md.
|
|
@@ -0,0 +1,573 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: powerbi-pbip-forensics
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Evidence-based static forensics for Power BI PBIP/PBIR/TMDL projects and Performance Analyzer logs.
|
|
5
|
+
Author: Vinicius de Souza Santos
|
|
6
|
+
License-Expression: LicenseRef-Proprietary
|
|
7
|
+
Project-URL: Homepage, https://github.com/ViniciusKanh/powerbi-pbip-forensics
|
|
8
|
+
Project-URL: Repository, https://github.com/ViniciusKanh/powerbi-pbip-forensics
|
|
9
|
+
Project-URL: Documentation, https://github.com/ViniciusKanh/powerbi-pbip-forensics#readme
|
|
10
|
+
Project-URL: Changelog, https://github.com/ViniciusKanh/powerbi-pbip-forensics/blob/main/CHANGELOG.md
|
|
11
|
+
Project-URL: Issues, https://github.com/ViniciusKanh/powerbi-pbip-forensics/issues
|
|
12
|
+
Keywords: power-bi,pbip,pbir,tmdl,dax,audit,forensics
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Intended Audience :: Information Technology
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Operating System :: OS Independent
|
|
22
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
23
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
24
|
+
Classifier: Operating System :: MacOS
|
|
25
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
26
|
+
Classifier: Topic :: Office/Business
|
|
27
|
+
Classifier: Natural Language :: English
|
|
28
|
+
Classifier: Natural Language :: Portuguese (Brazilian)
|
|
29
|
+
Classifier: Typing :: Typed
|
|
30
|
+
Requires-Python: >=3.11
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
License-File: LICENSE
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
35
|
+
Requires-Dist: pytest-cov>=5; extra == "dev"
|
|
36
|
+
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
37
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
38
|
+
Requires-Dist: build>=1.2; extra == "dev"
|
|
39
|
+
Requires-Dist: twine>=5.1; extra == "dev"
|
|
40
|
+
Requires-Dist: setuptools>=77; extra == "dev"
|
|
41
|
+
Requires-Dist: wheel>=0.43; extra == "dev"
|
|
42
|
+
Dynamic: license-file
|
|
43
|
+
|
|
44
|
+
<div align="center">
|
|
45
|
+
|
|
46
|
+
<img src="docs/assets/logo-512.png" alt="Power BI PBIP Forensics" width="200">
|
|
47
|
+
|
|
48
|
+
# Power BI PBIP Forensics
|
|
49
|
+
|
|
50
|
+
### Ask your AI agent *why* your Power BI report behaves the way it does, and get answers backed by evidence from your project files.
|
|
51
|
+
|
|
52
|
+

|
|
53
|
+

|
|
54
|
+

|
|
55
|
+

|
|
56
|
+

|
|
57
|
+

|
|
58
|
+

|
|
59
|
+
|
|
60
|
+
[What it does](#-what-it-does) •
|
|
61
|
+
[Report tour](#-report-tour) •
|
|
62
|
+
[How the skill works](#-how-the-skill-works) •
|
|
63
|
+
[Quick start](#-quick-start) •
|
|
64
|
+
[Ask it](#-what-you-can-ask) •
|
|
65
|
+
[Engine](#%EF%B8%8F-inside-the-engine) •
|
|
66
|
+
[Scripts](#-skill-scripts) •
|
|
67
|
+
[Safety](#%EF%B8%8F-safety-and-privacy) •
|
|
68
|
+
[Developers](#-for-developers)
|
|
69
|
+
|
|
70
|
+
<br>
|
|
71
|
+
|
|
72
|
+
<img src="docs/assets/report-dark.png" alt="Audit report overview in dark mode" width="900">
|
|
73
|
+
|
|
74
|
+
<sub>Interactive HTML report generated from the bundled synthetic project (`examples/synthetic_project`).</sub>
|
|
75
|
+
|
|
76
|
+
</div>
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 🔎 What it does
|
|
81
|
+
|
|
82
|
+
**Power BI PBIP Forensics** is an AI agent skill, with a Python engine behind it, that audits Power BI projects
|
|
83
|
+
saved in the **PBIP** format. It reads the report definition (**PBIR**) and the semantic model (**TMDL** or
|
|
84
|
+
`model.bim`) as text, builds the relationship graph and the DAX dependency graph, and explains:
|
|
85
|
+
|
|
86
|
+
- 🔗 **Filters that do not propagate**: inactive relationships, one-way relationships blocking the path, disconnected tables, ambiguous paths.
|
|
87
|
+
- 🧮 **DAX problems**: missing references, circular dependencies, `ALL`/`REMOVEFILTERS` overriding slicers, totals that differ from the visible rows, costly patterns.
|
|
88
|
+
- 📊 **Broken visuals**: fields that no longer exist in the model, tables combined without a relationship, page filters that cannot reach the measures.
|
|
89
|
+
- 🧹 **Cleanup opportunities**: unused measures and columns, measures without a format, visible foreign keys, auto date tables, overloaded pages.
|
|
90
|
+
- 🐢 **Slow visuals**: ranked from a Performance Analyzer export (*preview*).
|
|
91
|
+
- 🔀 **Change impact**: what changed between two versions, and which measures and visuals to retest.
|
|
92
|
+
|
|
93
|
+
It is written for **two audiences at once**: a business user gets a health score, a plain-language summary and a
|
|
94
|
+
short list of what to fix first; a BI developer gets file paths, line numbers, evidence and a way to verify each
|
|
95
|
+
finding.
|
|
96
|
+
|
|
97
|
+
Every finding states:
|
|
98
|
+
|
|
99
|
+
| | |
|
|
100
|
+
|---|---|
|
|
101
|
+
| **Where** | File path, line and object |
|
|
102
|
+
| **Why** | The evidence that triggered it |
|
|
103
|
+
| **How sure** | `confirmed` · `potential` · `inconclusive` |
|
|
104
|
+
| **What to do** | A suggested fix |
|
|
105
|
+
| **How to verify** | A check you can run in Power BI Desktop |
|
|
106
|
+
|
|
107
|
+
## 🖼️ Report tour
|
|
108
|
+
|
|
109
|
+
One command produces a single self-contained HTML file (no internet needed, light and dark themes, works on
|
|
110
|
+
mobile), plus Markdown and JSON versions. All screenshots below come from the bundled synthetic project.
|
|
111
|
+
|
|
112
|
+
### 1. Health score and plain-language summary
|
|
113
|
+
|
|
114
|
+
Six gauges score the data model, DAX measures, report & visuals, performance and project files. The score is an
|
|
115
|
+
**indicative** summary of the findings, and its formula is printed in the report. Below the gauges, a short
|
|
116
|
+
summary explains the situation without jargon.
|
|
117
|
+
|
|
118
|
+
<img src="docs/assets/report-scores.png" alt="Health score gauges and plain-language summary" width="900">
|
|
119
|
+
|
|
120
|
+
### 2. What to do first
|
|
121
|
+
|
|
122
|
+
Findings are grouped by rule and turned into actions, ranked by severity and effort (**quick win**, **medium
|
|
123
|
+
effort**, **structural**). Each card links to the detailed findings.
|
|
124
|
+
|
|
125
|
+
<img src="docs/assets/report-quick-wins.png" alt="Prioritised action cards" width="900">
|
|
126
|
+
|
|
127
|
+
### 3. Findings with evidence
|
|
128
|
+
|
|
129
|
+
Filter by severity, status, category or rule, or search by text. Each finding opens to show the source file, the
|
|
130
|
+
evidence, the impact, a recommendation and how to verify it.
|
|
131
|
+
|
|
132
|
+
<img src="docs/assets/report-findings.png" alt="Expanded finding with evidence" width="900">
|
|
133
|
+
|
|
134
|
+
### 4. Model map
|
|
135
|
+
|
|
136
|
+
The relationship diagram is laid out in layers: dimensions, bridges, facts and disconnected tables. Inactive
|
|
137
|
+
relationships are dashed, bidirectional ones are orange and **ambiguous filter paths are red**. Auto date tables
|
|
138
|
+
are hidden to keep the map readable.
|
|
139
|
+
|
|
140
|
+
<img src="docs/assets/report-model-map.png" alt="Semantic model relationship map" width="900">
|
|
141
|
+
|
|
142
|
+
### 5. Measures
|
|
143
|
+
|
|
144
|
+
The most complex measures (functions, iterators, nesting, dependency depth), the central measures that the rest
|
|
145
|
+
of the model depends on, and how measures are spread across display folders.
|
|
146
|
+
|
|
147
|
+
<img src="docs/assets/report-measures.png" alt="Measure complexity and hub statistics" width="900">
|
|
148
|
+
|
|
149
|
+
### 6. Pages and performance
|
|
150
|
+
|
|
151
|
+
One card per page shows visuals, slicers, filters, measures, custom visuals, broken bindings and the tables used.
|
|
152
|
+
When a Performance Analyzer export is available, visuals are ranked by measured time split into DAX query,
|
|
153
|
+
visual display and other.
|
|
154
|
+
|
|
155
|
+
<img src="docs/assets/report-pages.png" alt="Page cards" width="900">
|
|
156
|
+
<img src="docs/assets/report-performance.png" alt="Performance Analyzer ranking" width="900">
|
|
157
|
+
|
|
158
|
+
The report also includes a rules overview, change impact, root-cause hypotheses, recommended actions, limitations
|
|
159
|
+
and the full inventory (tables, columns, measures, relationships and data-source connectors).
|
|
160
|
+
|
|
161
|
+
## 🤖 How the skill works
|
|
162
|
+
|
|
163
|
+
The skill is a folder with a `SKILL.md` (instructions for the agent), seven standalone Python scripts,
|
|
164
|
+
references and answer templates. You talk to the agent; the agent decides which scripts to run.
|
|
165
|
+
|
|
166
|
+
```mermaid
|
|
167
|
+
sequenceDiagram
|
|
168
|
+
actor U as You
|
|
169
|
+
participant A as AI agent
|
|
170
|
+
participant S as Skill scripts (local)
|
|
171
|
+
participant P as PBIP folder (read-only)
|
|
172
|
+
U->>A: "Why does this table show unrelated accounts?"
|
|
173
|
+
A->>A: Reads SKILL.md and picks the scripts
|
|
174
|
+
A->>U: Asks permission to read the project folder
|
|
175
|
+
A->>S: pbip_visual_deps.py --from-table Customer --to-table Account
|
|
176
|
+
S->>P: Reads .pbip, PBIR and TMDL files as text
|
|
177
|
+
S-->>A: JSON with findings, evidence and limits
|
|
178
|
+
A-->>U: Answer: evidence, ranked hypotheses, how to verify, limitations
|
|
179
|
+
A->>S: pbip_full_audit.py (when asked for a full audit)
|
|
180
|
+
S-->>U: audit-report.html · .md · findings.json
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
1. **Trigger.** You ask a question about a Power BI project, or ask for an audit.
|
|
184
|
+
2. **Scope.** The agent asks which folder it may read and writes outputs to a separate folder.
|
|
185
|
+
3. **Analysis.** The agent runs only the scripts the question needs: inventory, model audit, visual
|
|
186
|
+
dependencies, performance log, diff, or the one-shot full audit.
|
|
187
|
+
4. **Answer.** The agent keeps **script evidence** separate from **its own reasoning**, ranks hypotheses by
|
|
188
|
+
confidence, tells you how to verify each one in Power BI Desktop, and states the limits of a static analysis
|
|
189
|
+
(template: [`templates/investigation-response.md`](agensi/powerbi-pbip-forensics/templates/investigation-response.md)).
|
|
190
|
+
5. **Report.** For audits, it produces the interactive HTML report shown above.
|
|
191
|
+
|
|
192
|
+
Nothing is executed from the project: DAX, M and JSON are parsed as data. Nothing leaves your machine.
|
|
193
|
+
|
|
194
|
+
## 🚀 Quick start
|
|
195
|
+
|
|
196
|
+
> **Requirements:** Python **3.11+** (standard library only) and a report saved as a Power BI project
|
|
197
|
+
> (*File → Save as → Power BI project (.pbip)*). Binary `.pbix` files are not supported.
|
|
198
|
+
|
|
199
|
+
### Option A: as an agent skill
|
|
200
|
+
|
|
201
|
+
1. Get the skill: buy it on **Agensi**, or use the folder `agensi/powerbi-pbip-forensics/` from this repository.
|
|
202
|
+
2. Install it where your agent loads skills. For **Claude Code**:
|
|
203
|
+
|
|
204
|
+
```powershell
|
|
205
|
+
# Windows (PowerShell)
|
|
206
|
+
Copy-Item -Recurse .\agensi\powerbi-pbip-forensics "$env:USERPROFILE\.claude\skills\powerbi-pbip-forensics"
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
# Linux / macOS
|
|
211
|
+
cp -r agensi/powerbi-pbip-forensics ~/.claude/skills/powerbi-pbip-forensics
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
For other agents, point them to `SKILL.md`. Any agent that can read Markdown and run local Python scripts can
|
|
215
|
+
use the skill.
|
|
216
|
+
3. Open your agent in the folder that contains your `.pbip` project and ask a question (see below).
|
|
217
|
+
|
|
218
|
+
### Option B: one-click audit (Windows)
|
|
219
|
+
|
|
220
|
+
Drag your PBIP project folder onto **`pbip-audit.cmd`**, or run:
|
|
221
|
+
|
|
222
|
+
```powershell
|
|
223
|
+
.\pbip-audit.cmd "C:\BI\MyProject"
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
It skips backup folders, auto-detects a Performance Analyzer export inside the project, writes the report to
|
|
227
|
+
`C:\BI\MyProject-forensics\` and opens the HTML report. The equivalent engine command is
|
|
228
|
+
`py -m pbip_forensics run --project <folder> --open --lang pt-BR` (with `PYTHONPATH=src`).
|
|
229
|
+
|
|
230
|
+
### Option C: run the scripts yourself
|
|
231
|
+
|
|
232
|
+
```powershell
|
|
233
|
+
$S = ".\agensi\powerbi-pbip-forensics\scripts"
|
|
234
|
+
$P = "C:\BI\MyProject" # your PBIP folder (read-only)
|
|
235
|
+
$O = "C:\BI\audit" # output folder, must be outside the project
|
|
236
|
+
|
|
237
|
+
py $S\pbip_full_audit.py --project $P --output $O --lang pt-BR # everything + HTML report
|
|
238
|
+
py $S\pbip_visual_deps.py --project $P --from-table Customer --to-table Account --output $O
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Open `C:\BI\audit\audit-report.html`. Use `--lang pt-BR` for Brazilian Portuguese headings and summaries.
|
|
242
|
+
|
|
243
|
+
## 📦 Install the CLI (Python package)
|
|
244
|
+
|
|
245
|
+
> **Requirements:** Python **3.11, 3.12 or 3.13** on Windows, Linux or macOS. The engine uses only the
|
|
246
|
+
> standard library at runtime — installing the CLI pulls in no third-party dependencies.
|
|
247
|
+
|
|
248
|
+
<details>
|
|
249
|
+
<summary><b>Install from a wheel (recommended — offline-friendly)</b></summary>
|
|
250
|
+
|
|
251
|
+
Build artifacts are **not** published on PyPI yet (see [Future publication](#-future-publication-not-done-yet)
|
|
252
|
+
below). Until then, install directly from a built wheel — built locally with `python -m build` (see
|
|
253
|
+
[For developers](#-for-developers)), or one you were given by the author:
|
|
254
|
+
|
|
255
|
+
```powershell
|
|
256
|
+
# Windows (PowerShell)
|
|
257
|
+
py -3 -m venv .venv
|
|
258
|
+
.\.venv\Scripts\pip install .\dist\powerbi_pbip_forensics-1.0.0-py3-none-any.whl
|
|
259
|
+
.\.venv\Scripts\pbip-forensics --version
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
# Linux / macOS
|
|
264
|
+
python3 -m venv .venv
|
|
265
|
+
./.venv/bin/pip install ./dist/powerbi_pbip_forensics-1.0.0-py3-none-any.whl
|
|
266
|
+
./.venv/bin/pbip-forensics --version
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
A virtual environment is not required — `pip install --user <wheel>` or `pipx install <wheel>` also work —
|
|
270
|
+
but it keeps the install isolated and easy to remove (`pipx` additionally puts `pbip-forensics` on your
|
|
271
|
+
`PATH` automatically).
|
|
272
|
+
</details>
|
|
273
|
+
|
|
274
|
+
<details>
|
|
275
|
+
<summary><b>Install from a private index</b></summary>
|
|
276
|
+
|
|
277
|
+
If you host the wheel on a private index or simple-repository (Artifactory, Azure Artifacts, a private
|
|
278
|
+
`devpi`, a signed URL to cloud storage, etc.):
|
|
279
|
+
|
|
280
|
+
```bash
|
|
281
|
+
pip install powerbi-pbip-forensics --index-url https://<your-private-index>/simple/
|
|
282
|
+
```
|
|
283
|
+
</details>
|
|
284
|
+
|
|
285
|
+
<details>
|
|
286
|
+
<summary><b>Basic commands</b></summary>
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
pbip-forensics --version
|
|
290
|
+
pbip-forensics --help
|
|
291
|
+
pbip-forensics run --project "C:\BI\MyProject" --open --lang pt-BR
|
|
292
|
+
pbip-forensics scan --project "C:\BI\MyProject"
|
|
293
|
+
pbip-forensics audit --project "C:\BI\MyProject" --output .\reports --format all --fail-on HIGH
|
|
294
|
+
pbip-forensics performance --input .\reports\performance.json
|
|
295
|
+
pbip-forensics diff --before "C:\BI\MyProject" --after "C:\BI\MyProject_v2"
|
|
296
|
+
pbip-forensics investigate --project "C:\BI\MyProject" --from-table Customer --to-table Account
|
|
297
|
+
pbip-forensics report --input .\reports\findings.json --format html
|
|
298
|
+
python -m pbip_forensics --version # equivalent module entry point, no PATH needed
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
`--project` is read-only and is never modified. `--output` must point **outside** the audited project (the
|
|
302
|
+
tool refuses to write inside it). `--fail-on {CRITICAL,HIGH,MEDIUM,LOW,INFO}` makes `audit`/`run` return exit
|
|
303
|
+
code `1` when a finding at or above that severity exists — wire this into CI to gate a pipeline on Power BI
|
|
304
|
+
quality. See [Exit codes](#exit-codes) below.
|
|
305
|
+
</details>
|
|
306
|
+
|
|
307
|
+
<details>
|
|
308
|
+
<summary><b>Update / uninstall / check version</b></summary>
|
|
309
|
+
|
|
310
|
+
```bash
|
|
311
|
+
pip install --force-reinstall ./dist/powerbi_pbip_forensics-<new-version>-py3-none-any.whl # update
|
|
312
|
+
pip uninstall powerbi-pbip-forensics # uninstall
|
|
313
|
+
pip show powerbi-pbip-forensics # installed version
|
|
314
|
+
pbip-forensics --version # CLI version
|
|
315
|
+
```
|
|
316
|
+
</details>
|
|
317
|
+
|
|
318
|
+
<details>
|
|
319
|
+
<summary><a name="exit-codes"></a><b>Exit codes</b></summary>
|
|
320
|
+
|
|
321
|
+
| Code | Meaning |
|
|
322
|
+
|---|---|
|
|
323
|
+
| 0 | Success (no finding reached `--fail-on`, or `--fail-on` not set) |
|
|
324
|
+
| 1 | At least one finding at/above the `--fail-on` severity |
|
|
325
|
+
| 2 | Invalid input (bad path, bad JSON, missing required option) |
|
|
326
|
+
| 3 | A configured limit was exceeded (file count, file size) |
|
|
327
|
+
| 4 | Refused by security policy (output inside the audited project, sensitive file, out-of-scope path) |
|
|
328
|
+
| 5 | Invalid Performance Analyzer log |
|
|
329
|
+
| 10 | Internal error (re-run with `--debug` for the traceback) |
|
|
330
|
+
</details>
|
|
331
|
+
|
|
332
|
+
<details>
|
|
333
|
+
<summary><b>CI/CD integration</b></summary>
|
|
334
|
+
|
|
335
|
+
```yaml
|
|
336
|
+
# Example: GitHub Actions step that fails the pipeline on HIGH+ findings
|
|
337
|
+
- name: Audit Power BI project
|
|
338
|
+
run: |
|
|
339
|
+
pip install ./dist/powerbi_pbip_forensics-1.0.0-py3-none-any.whl
|
|
340
|
+
pbip-forensics audit --project "$GITHUB_WORKSPACE/MyProject.Report/.." \
|
|
341
|
+
--output "$RUNNER_TEMP/pbip-audit" --format all --fail-on HIGH
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
The tool never reaches the network and never phones home (see [Safety and privacy](#🛡%EF%B8%8F-safety-and-privacy));
|
|
345
|
+
exit codes make it CI-friendly without extra tooling. For how *this repository's own* CI is set up (lint,
|
|
346
|
+
type-check, tests, build, no publishing), see
|
|
347
|
+
[`.github/workflows/python-package-ci.yml`](.github/workflows/python-package-ci.yml).
|
|
348
|
+
</details>
|
|
349
|
+
|
|
350
|
+
<details>
|
|
351
|
+
<summary><b>Privacy policy, license and limitations</b></summary>
|
|
352
|
+
|
|
353
|
+
- **Privacy:** static, local, read-only analysis. DAX/M/JSON are parsed as text, never executed. No
|
|
354
|
+
telemetry, no network calls, no data leaves your machine. See
|
|
355
|
+
[🛡️ Safety and privacy](#🛡%EF%B8%8F-safety-and-privacy) below and
|
|
356
|
+
[`src/pbip_forensics/security/safety.py`](src/pbip_forensics/security/safety.py).
|
|
357
|
+
- **License:** proprietary (`LicenseRef-Proprietary`); installing or receiving the package does not grant
|
|
358
|
+
any right to use, copy or redistribute it beyond what [LICENSE](LICENSE) allows. See
|
|
359
|
+
[📄 License](#-license) and [docs/licensing-options.md](docs/licensing-options.md).
|
|
360
|
+
- **Limitations:** static analysis only, with documented gaps in filter-propagation, DAX coverage and
|
|
361
|
+
format support. See [docs/limitations.md](docs/limitations.md) before relying on a finding for a
|
|
362
|
+
production decision.
|
|
363
|
+
|
|
364
|
+
</details>
|
|
365
|
+
|
|
366
|
+
<details>
|
|
367
|
+
<summary><a name="-future-publication-not-done-yet"></a><b>Future publication (not done yet)</b></summary>
|
|
368
|
+
|
|
369
|
+
`powerbi-pbip-forensics` is **not currently published** on PyPI or TestPyPI, and no publish has been run as
|
|
370
|
+
part of preparing this CLI. The `Private :: Do Not Upload` classifier in `pyproject.toml` is a deliberate
|
|
371
|
+
safeguard: PyPI refuses any upload carrying it, so an accidental `twine upload` cannot leak the package.
|
|
372
|
+
Publishing requires removing that classifier and explicit author authorization — see
|
|
373
|
+
[docs/licensing-options.md](docs/licensing-options.md) for the licensing decision that must be made first,
|
|
374
|
+
and the project's internal build report for the step-by-step TestPyPI/PyPI procedure once authorized.
|
|
375
|
+
</details>
|
|
376
|
+
|
|
377
|
+
## 💬 What you can ask
|
|
378
|
+
|
|
379
|
+
| You ask the agent | It checks |
|
|
380
|
+
|---|---|
|
|
381
|
+
| *"Audit this project before I publish it."* | All rules, health score, prioritised actions, full HTML report |
|
|
382
|
+
| *"Why is the Customer Accounts table showing accounts unrelated to the selected customer?"* | Relationship paths hop by hop, inactive or one-way relationships, visual bindings |
|
|
383
|
+
| *"Why does **Total Revenue** ignore my slicer?"* | `ALL` / `REMOVEFILTERS` / `CROSSFILTER` in the measure and its dependencies |
|
|
384
|
+
| *"My total is different from the sum of the rows. What should I check?"* | Non-additive patterns (`IF` on measures, `DISTINCTCOUNT`, `HASONEVALUE`), many-to-many relationships |
|
|
385
|
+
| *"What can I delete to make the model lighter?"* | Unused measures and columns, auto date tables, isolated tables |
|
|
386
|
+
| *"Which visuals are slowing this page down?"* | Measured DAX query, visual display and *Other* times from your Performance Analyzer export |
|
|
387
|
+
| *"Compare `v1` and `v2`. What do I need to retest?"* | Changed measures, columns and relationships, and every dependent measure and visual |
|
|
388
|
+
|
|
389
|
+
### Example answer
|
|
390
|
+
|
|
391
|
+
Real script output from `examples/synthetic_project`:
|
|
392
|
+
|
|
393
|
+
```text
|
|
394
|
+
VIS006 HIGH potential Unrelated tables combined in 'Customer Accounts' (tableEx): 'Account' and 'Customer'
|
|
395
|
+
No active relationship path between them in either direction
|
|
396
|
+
→ ContosoRetail.Report/definition/pages/overview01/visuals/v_table_accounts/visual.json
|
|
397
|
+
|
|
398
|
+
MOD002 LOW potential Inactive relationship not activated by any measure: Account -> Customer
|
|
399
|
+
'Account'[CustomerKey] (many) -> 'Customer'[CustomerKey] (one) · isActive: false
|
|
400
|
+
→ ContosoRetail.SemanticModel/definition/relationships.tmdl:27
|
|
401
|
+
|
|
402
|
+
Investigation Customer → Account
|
|
403
|
+
BLOCKED PATH: 'Customer' -> 'Account' via 'Account'[CustomerKey] -> 'Customer'[CustomerKey] [INACTIVE]
|
|
404
|
+
#1 [high confidence] Inactive relationship on the only path from 'Customer' to 'Account'.
|
|
405
|
+
Verify: confirm isActive=false in Model view; test a measure with USERELATIONSHIP(...).
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
## ⚙️ Inside the engine
|
|
409
|
+
|
|
410
|
+
```mermaid
|
|
411
|
+
flowchart LR
|
|
412
|
+
A[PBIP folder<br/>read-only] --> B[Discovery<br/>.pbip · .Report · .SemanticModel]
|
|
413
|
+
B --> C[Parsers<br/>PBIR · TMDL · model.bim]
|
|
414
|
+
C --> D[DAX tokenizer<br/>call tree · references]
|
|
415
|
+
C --> E[Relationship graph<br/>paths · cycles · roles]
|
|
416
|
+
D --> F[39 rules<br/>MOD · DAX · VIS · COL · PERF]
|
|
417
|
+
E --> F
|
|
418
|
+
G[Performance Analyzer<br/>export .json] --> F
|
|
419
|
+
F --> H[Findings with evidence<br/>+ ranked hypotheses]
|
|
420
|
+
H --> I[Insights<br/>scores · summary · actions · model map]
|
|
421
|
+
I --> J[Report<br/>HTML · Markdown · JSON]
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
- **Real parsing, not guessing.** The TMDL parser follows indentation, so it handles multi-line expressions,
|
|
425
|
+
triple-backtick blocks, quoted names, hierarchies and sort-by columns. The DAX tokenizer respects strings,
|
|
426
|
+
comments and `[references]`. PBIR fields follow Microsoft's published JSON schemas, including fields used only
|
|
427
|
+
in conditional formatting.
|
|
428
|
+
- **Graph algorithms.** Filter paths are direction-aware. Blocked paths are explained hop by hop. Ambiguous loops
|
|
429
|
+
are separated from harmless ones, and measure cycles are found with Tarjan's algorithm.
|
|
430
|
+
- **False-positive safeguards.** Lookup and parameter tables, measures that link tables, role-playing dates and
|
|
431
|
+
formatting-only references are recognised. Each rule's safeguard is documented.
|
|
432
|
+
- **Honest statuses.** `confirmed` means proven by the files or measured in a log. `potential` means a risk to
|
|
433
|
+
verify. `inconclusive` means the engine could not interpret it. No invented percentages, values or timings.
|
|
434
|
+
|
|
435
|
+
| Rule family | What it covers |
|
|
436
|
+
|---|---|
|
|
437
|
+
| `PRS` / `SEC` | Parsing problems, missing files, unsupported formats, items skipped by the safety policy |
|
|
438
|
+
| `MOD001`–`MOD010` | Broken, inactive, bidirectional, many-to-many and ambiguous relationships; disconnected tables; key type mismatch; auto date tables; visible foreign keys |
|
|
439
|
+
| `DAX001`–`DAX014` | Missing references, circular dependencies, costly `FILTER`/iterators/context transition, filter overrides, non-additive totals, `/` without `DIVIDE`, unused or unformatted measures |
|
|
440
|
+
| `VIS001`–`VIS008` | Broken bindings, uninterpretable visuals, filters that cannot reach measures, unrelated tables in a grid, overloaded pages |
|
|
441
|
+
| `COL001` | Columns with no detected use |
|
|
442
|
+
| `PERF001` | Visuals over the measured time thresholds |
|
|
443
|
+
|
|
444
|
+
Full rule list with severities and safeguards: [docs/diagnostic-rules.md](docs/diagnostic-rules.md).
|
|
445
|
+
|
|
446
|
+
**Health score formula:** `score = 100 × exp(−Σ weight(severity) × factor(status) / 40)`, with weights CRITICAL 20,
|
|
447
|
+
HIGH 8, MEDIUM 3, LOW 1, INFO 0 and factors confirmed 1, potential 0.5, inconclusive 0.25. The overall score is the
|
|
448
|
+
mean of the measured areas. It summarises the findings; it is not a quality certificate.
|
|
449
|
+
|
|
450
|
+
## 🧰 Skill scripts
|
|
451
|
+
|
|
452
|
+
Each script is **standalone**: one file, Python standard library only, no network. It reads only the paths you
|
|
453
|
+
pass, writes only to `--output`, and works on Windows, Linux and macOS.
|
|
454
|
+
|
|
455
|
+
| Script | Purpose | Main arguments |
|
|
456
|
+
|---|---|---|
|
|
457
|
+
| `pbip_full_audit.py` | **One-shot**: all analyses + interactive HTML/Markdown/JSON report | `--project` `--output` `--lang` |
|
|
458
|
+
| `pbip_inspect.py` | Inventory of reports, pages, visuals, tables, measures, relationships and data-source connectors | `--project` |
|
|
459
|
+
| `pbip_model_audit.py` | Relationship and model structure checks plus DAX static analysis | `--project` |
|
|
460
|
+
| `pbip_visual_deps.py` | Page → Visual → Field → Table map, broken bindings, filter investigation | `--project` `--from-table` `--to-table` `--measure` `--visual` |
|
|
461
|
+
| `pbip_perf_log.py` | Ranks visuals by measured duration *(preview)* | `--input` `--medium-ms` `--high-ms` |
|
|
462
|
+
| `pbip_diff.py` | Changes between two versions and their impact | `--before` `--after` |
|
|
463
|
+
| `pbip_report.py` | Merges the JSON outputs into Markdown, HTML and JSON | `--input …` `--format` `--lang en\|pt-BR` |
|
|
464
|
+
|
|
465
|
+
**Exit codes:** `0` OK · `2` invalid input · `3` size limit exceeded · `4` refused by the safety policy ·
|
|
466
|
+
`5` invalid performance log · `10` internal error.
|
|
467
|
+
|
|
468
|
+
## 🛡️ Safety and privacy
|
|
469
|
+
|
|
470
|
+
- **Read-only.** The project is never modified, and reports must be written outside it.
|
|
471
|
+
- **Scope-locked.** Only the folder you authorize is read. Symbolic links that point outside it are not followed.
|
|
472
|
+
- **No secrets.** `.env`, keys, certificates, `localSettings.json` and `cache.abf` are never opened. Only connector
|
|
473
|
+
names (for example `Sql.Database`) are reported, never connection strings or credentials.
|
|
474
|
+
- **No execution.** DAX, M and JSON are parsed as data and never evaluated.
|
|
475
|
+
- **No network.** Everything runs locally and offline; the HTML report has no external resources.
|
|
476
|
+
- **Untrusted content.** Text inside the project, such as measure names and descriptions, is treated as data and
|
|
477
|
+
never as instructions. HTML output is escaped.
|
|
478
|
+
|
|
479
|
+
## ⚠️ Limitations
|
|
480
|
+
|
|
481
|
+
- **Static analysis.** No DAX is executed and no data is read, so the skill never claims values or totals.
|
|
482
|
+
- **Formats.** PBIX/PBIT are not supported. Support for the older PBIR-Legacy report format is best-effort.
|
|
483
|
+
- **Usage scope.** Unused measures/columns are reported only when every bound report is PBIR and fully
|
|
484
|
+
interpretable; RLS roles, other reports and external tools are not visible. Confirm with lineage before removing.
|
|
485
|
+
- **Not modelled:** calculation groups, row-level security, `TREATAS` virtual relationships, and visual
|
|
486
|
+
interactions or bookmarks.
|
|
487
|
+
- **Performance Analyzer (preview).** Validated with synthetic exports only.
|
|
488
|
+
- **Language.** Finding texts are in English. Headings, scores, summaries and action titles are available in
|
|
489
|
+
English and Brazilian Portuguese.
|
|
490
|
+
|
|
491
|
+
Details: [docs/limitations.md](docs/limitations.md).
|
|
492
|
+
|
|
493
|
+
---
|
|
494
|
+
|
|
495
|
+
## 👩💻 For developers
|
|
496
|
+
|
|
497
|
+
<details>
|
|
498
|
+
<summary><b>Engine CLI</b></summary>
|
|
499
|
+
|
|
500
|
+
```bash
|
|
501
|
+
pip install -e ".[dev]"
|
|
502
|
+
pbip-forensics run --project ./examples/synthetic_project [--lang pt-BR] [--open]
|
|
503
|
+
pbip-forensics scan --project ./examples/synthetic_project
|
|
504
|
+
pbip-forensics audit --project ./examples/synthetic_project --output ./reports [--performance perf.json] [--fail-on HIGH]
|
|
505
|
+
pbip-forensics investigate --project ./examples/synthetic_project --from-table Customer --to-table Account
|
|
506
|
+
pbip-forensics performance --input ./examples/sample_performance/performance.json
|
|
507
|
+
pbip-forensics diff --before ./examples/synthetic_project --after ./examples/synthetic_project_v2
|
|
508
|
+
pbip-forensics report --input ./reports/findings.json --format html
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
`--fail-on` returns exit code 1 when there are findings at or above the given severity, which is useful in CI.
|
|
512
|
+
</details>
|
|
513
|
+
|
|
514
|
+
<details>
|
|
515
|
+
<summary><b>Repository layout</b></summary>
|
|
516
|
+
|
|
517
|
+
```text
|
|
518
|
+
src/pbip_forensics/ engine: security · discovery · parsers · graph · analyzers · findings · reporting · cli
|
|
519
|
+
agensi/powerbi-pbip-forensics/ the skill: SKILL.md · scripts/ (generated) · references/ · templates/
|
|
520
|
+
tools/ build_skill · package_agensi · make_fixtures · run_demo · gen_docs · script_metrics
|
|
521
|
+
tests/ unit · integration (including isolated script parity) · packaging (wheel/sdist install) · fixtures
|
|
522
|
+
examples/ synthetic projects · sample Performance Analyzer log · sample reports
|
|
523
|
+
docs/ architecture · formats · rules · limitations · validation · packaging & publishing · Agensi docs · assets
|
|
524
|
+
```
|
|
525
|
+
</details>
|
|
526
|
+
|
|
527
|
+
<details>
|
|
528
|
+
<summary><b>Tests and packaging</b></summary>
|
|
529
|
+
|
|
530
|
+
```bash
|
|
531
|
+
python -m pytest -o addopts="" -q # 112 tests (101 engine/skill + 11 packaging)
|
|
532
|
+
python -m pytest -q -m "not packaging" # fast subset, skips the real build+install tests
|
|
533
|
+
ruff check src tests tools && mypy
|
|
534
|
+
python tools/build_skill.py # regenerate standalone scripts from the engine
|
|
535
|
+
python tools/gen_docs.py # regenerate the rule catalog docs
|
|
536
|
+
python tools/package_agensi.py # build and validate dist/powerbi-pbip-forensics-v1.0.0.zip
|
|
537
|
+
|
|
538
|
+
python -m build # build the pip wheel + sdist into dist/
|
|
539
|
+
python -m twine check dist/*.whl dist/*.tar.gz # validate package metadata
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
Each generated skill script is also run alone, under `python -I`, and its output is compared with the
|
|
543
|
+
engine's (see [docs/validation-results.md](docs/validation-results.md)). The `tests/packaging/` suite builds
|
|
544
|
+
the real wheel/sdist and installs each in a fresh, isolated virtual environment to prove the CLI works with
|
|
545
|
+
no `PYTHONPATH` and no repository path on `sys.path` (see
|
|
546
|
+
[docs/python-packaging.md](docs/python-packaging.md) for the full packaging and future-publication notes).
|
|
547
|
+
</details>
|
|
548
|
+
|
|
549
|
+
### Documentation
|
|
550
|
+
|
|
551
|
+
| | |
|
|
552
|
+
|---|---|
|
|
553
|
+
| [Architecture](docs/architecture.md) | Modules, data flow, skill bundling |
|
|
554
|
+
| [Supported formats](docs/supported-formats.md) | PBIP / PBIR / TMDL / TMSL / Performance Analyzer fields and versions |
|
|
555
|
+
| [Diagnostic rules](docs/diagnostic-rules.md) | Every rule, its severity, status and false-positive safeguards |
|
|
556
|
+
| [Limitations](docs/limitations.md) | What is out of scope |
|
|
557
|
+
| [Validation results](docs/validation-results.md) | Measured tests, coverage, timing, parity |
|
|
558
|
+
| [SKILL.md](agensi/powerbi-pbip-forensics/SKILL.md) | Operational instructions for agents |
|
|
559
|
+
| [Publishing on Agensi](docs/PUBLISH_AGENSI.md) | Submission and post-publication test |
|
|
560
|
+
| [Python packaging & publishing](docs/python-packaging.md) | Wheel/sdist build, CI, and the TestPyPI/PyPI procedure (not yet executed) |
|
|
561
|
+
| [Changelog](CHANGELOG.md) | Release history |
|
|
562
|
+
|
|
563
|
+
## 📄 License
|
|
564
|
+
|
|
565
|
+
Copyright © 2026 **Vinicius de Souza Santos**. All rights reserved. This is proprietary software, and access to
|
|
566
|
+
this repository does not grant any right to use, copy or redistribute it. See [LICENSE](LICENSE).
|
|
567
|
+
|
|
568
|
+
Power BI, PBIP, PBIR, TMDL and DAX are Microsoft technologies. This project is not affiliated with or endorsed by
|
|
569
|
+
Microsoft.
|
|
570
|
+
|
|
571
|
+
<div align="center">
|
|
572
|
+
<sub>Made by <a href="https://github.com/ViniciusKanh">Vinicius de Souza Santos</a> · v1.0.0</sub>
|
|
573
|
+
</div>
|