Add table / matrix conditional formatting (data bar, colour scale, icon set).

Power BI stores conditional formatting on table-style visuals under singleVisual.objects.values (or columnFormatting on older builds), keyed by a queryRef that matches the column / measure bound to the visual's Values role. We write the canonical shape Power BI Desktop emits in current builds.

Parameters

column_name: The display name (Property) of the measure / column inside the Values projection. Matched case-insensitively against the prototypeQuery Select entries. format_type: One of dataBar, colorScale, iconSet. min_color, mid_color, max_color: Colour scale endpoints (and optional midpoint). Hex strings. bar_color: Data bar fill colour. icon_set: One of threeArrows, threeArrowsGray, threeTrafficLights, threeSymbols, threeFlags, fiveArrows.

Add (or update) a member (user/group) on a role.

member_type: 'external' (default, ExternalModelRoleMember — recommended for Power BI service) 'windows' (WindowsModelRoleMember — domain principal SID)

With overwrite=False (default), raises PowerBIDuplicateError if a member with the same member_name already exists on the role. With overwrite=True the existing member's identity_provider is refreshed (when external) and the response carries action="updated".

Add any visual to a report page — the single entry point for visual creation.

visual_type: card, labelled_card, multi_row_card, bar_chart, stacked_bar_chart, stacked_column_chart, clustered_column_chart, hundred_percent_stacked_bar_chart, hundred_percent_stacked_column_chart, ribbon_chart, line_chart, area_chart, stacked_area_chart, hundred_percent_stacked_area_chart, donut, pie_chart, treemap, funnel, table, waterfall, scatter_chart, combo_chart, slicer, gauge, kpi, matrix, map, text_box. config: per-type keys — categorical charts: category_column + value_measure (+ legend_column); axis charts: axis_column + value_measures (list); card/gauge: measure; table: columns (list); matrix: rows + values (lists); scatter: category_column + x_measure + y_measure; combo: category_column + bar_measures + line_measures; kpi: indicator_measure + trend_column; slicer: column (+ slicer_type); map: location (+ measure); text_box: text. Error messages name any missing key. Prefer pbi_add_visual_from_intent when you have a business intent rather than an exact type. dry_run: when True, run all validation and binding logic but skip the layout disk write — response carries dry_run=True and a write_log.

Plan a visual from a business-intent spec, then build it.

Same intent schema as pbi_plan_visual_tool. The chosen visual is created through the generic dispatcher, so all field validation and binding logic applies. dry_run=True plans and validates without writing the layout.

Apply a named format preset to a list of measures or columns.

Wraps pbi_set_format_tool so callers don't need to memorise the raw format string. Supported preset families: currency_eur(_k|_m), currency_usd, percent (0dp/1dp/2dp/4dp), thousands, millions, decimal_2, integer, integer_no_sep, date_iso, date_short_fr, date_short_us, date_long_fr, datetime_iso. Use pbi_list_format_presets_tool to inspect them.

Apply a one-shot visual style preset to an existing .pbix.

wallpaper_fit (optional) overrides the preset's default canvas image scaling. Must be one of Fit, Fill, Normal, Stretch (Power BI's enum). When omitted the preset's page.wallpaper.fit is used.

See module docstring for the full flow.

Detect missing, ambiguous, bidirectional, and orphaned model structures.

Compute non-overlapping (x, y, width, height) for visual specs on a column-based grid. Pure offline calculation.

Bulk-create Excel import queries for multiple tables.

Pre-build DBCC risk analysis on a tables spec.

Mirrors the input shape of pbi_create_persistent_report_tool and pbi_scaffold_pbix_tool. Pass the same tables list before calling the builder to catch empty-String-column risks up front.

Compare two extracted report versions by pages, visuals, and layout score.

Connect to Power BI Desktop and report the active instance.

Migrate an existing visual to a different type while preserving compatible field bindings.

Create a calculation group table with its Name column and optional calculation items.

items: list of {name, expression, format_string_expression?, ordinal?}.

Create or update a calculated column.

Create a %-of-total contribution measure.

DAX template:

DIVIDE([{base}], CALCULATE([{base}], ALL({scope_columns})))

scope_columns defines the denominator scope — typically the dimension columns whose total you want each row to be a percentage of (e.g. ["Categorie.Nom catégorie"] for "this category's % of all categories").

Generate and inject a CSV import Power Query for a table.

Generate and inject a folder import Power Query for a table.

Generate and inject an Excel import Power Query for a table.

Create or update a DAX measure.

Batch-create or update multiple DAX measures with a single SaveChanges call.

Each item in measures must have at minimum: name, expression. Optional keys: format_string, description, display_folder, is_hidden.

With dry_run=True, every measure is name + expression validated and the per-item planned_action is reported (would_create/would_update/ would_fail), but no model mutation happens — SaveChanges is never called. Use this for an LLM preflight before committing the batch.

Create a persistent PBIX with DataModel, DAX measures, relationships, pages, and native visuals.

prime_string_store (default True) injects a one-row sentinel into every empty Import table whose schema declares a String column, so Vertipaq's DBCC string-store consistency check passes on reopen. Disable only when you know the table will be populated by Power BI Desktop's first refresh (e.g. via a DirectQuery binding or a Power Query expression set after the PBIX is created).

style_preset (optional) names a built-in styling preset (glassmorph_dark, glassmorph_light, neon_cyber, minimal_corporate, dark_pro, or custom). When set, the matching preset is applied to the file via pbi_apply_style_preset_tool right after save, so the produced PBIX opens with wallpaper, card chrome, accent colours, and the preset's theme already wired up. style_wallpaper_path overrides the preset's default wallpaper; style_custom_spec is required when style_preset='custom'.

Create or update a single-column relationship.

With overwrite=False (default), raises PowerBIDuplicateError when a relationship between the same endpoint columns already exists. With overwrite=True the existing relationship is updated in place (cardinality / direction / is_active refreshed) and the response carries action="updated".

Create or update a model role.

Create a trailing rolling average measure.

DAX template:

AVERAGEX(DATESINPERIOD({date_table}[{date_column}], LASTDATE({date_table}[{date_column}]), -{window}, {granularity}), [{base}])

Create or update a calculated table.

Create a family of time-intelligence measures from a base measure.

Default patterns: YTD, MTD, QTD, SPY, YOY, YOY %, MA3. Each generated measure is named "{base_measure} {suffix}" (e.g. "Sales YTD") and lives on table (typically the same fact table as the base measure). Dependency-aware: requesting YOY% automatically adds YOY and SPY so the whole family resolves.

With format_inherit=True, each measure inherits base_measure's format string (best-effort lookup on the live model). format_string overrides that when supplied. Patterns that prescribe their own format (e.g. YOY % → "0.00%") win unless format_string is explicit.

With dry_run=True no model mutation occurs — the response carries a plan listing every measure that would be created/updated/skipped.

Create a Top-N filter measure.

DAX template:

IF(RANKX(ALL({dim_table}[{dim_column}]), [{rank_measure}], , DESC) <= {N}, [{base}], BLANK())

Use as the value of a chart visual to surface only the top N members of a dimension. rank_measure defaults to base_measure.

Create a period-over-period variance measure.

DAX template (parametrised by granularity ∈ {year, month, quarter}):

[{base}] - CALCULATE([{base}], DATEADD({date_table}[{date_column}], {offset}, {granularity}))

Default compare_period_offset = -1 ⇒ "current period vs previous one".

Delete a calculation group table.

Delete a column from a table.

Delete a DAX measure.

Delete a relationship by name or by endpoint columns.

Delete a model role.

Delete a table. Removes associated relationships and measures.

Return a structured, LLM-friendly snapshot of a report page.

One entry per visual with id/type/position, role-keyed bindings, formatting (title + axis titles + label_display_units), and a binding_health rollup (ok | missing_field | wrong_role) based on live-model validation when manager is supplied.

Detect cycles in the measure dependency graph.

Builds a graph of measure → referenced measures (parsed from DAX [Name] tokens that match a known measure name) and runs a DFS to find strongly connected cycles. Self-references are reported separately.

Detect text columns that look like dirty dates.

Execute lightweight DAX probes to detect visuals with no data.

Detect required visuals that are absent from a page.

Each requirement entry is a dict with at least visual_type and optionally count (default 1), contains_field (a reference like Date.Year that must appear in the visual's prototypeQuery), and label (free-form name surfaced in the report).

Detect table, column, and measure name collisions before writes.

Statically diagnose DBCC string-store risks on a built .pbix.

Returns a list of issues (each with a type and a short message) and a valid flag. Use this before opening the file in Power BI Desktop to avoid the round-trip through the modal repair dialog.

Aggregate render-risk diagnostic for visuals on disk.

Read-only. Walks the extracted layout and reports conditions known to make Power BI Desktop refuse to render a visual or surface an opaque internal error:

• Constant Y measure on a cartesian chart (line / combo / area / waterfall). The bug-0.92 family: a measure whose DAX expression has no column or measure reference (or returns BLANK() unconditionally) collapses every Y point to the same scalar with no axis dependency, which some PBI builds reject.

• Unresolved measure home table — the binding falls back to the synthetic $Measures entity which PBI refuses to plot.

• Missing column / measure / wrong reference kind in the live model (only when manager is supplied).

• Query-ref mismatch between projections and prototypeQuery Select entries.

A live manager enables DAX-expression heuristics for the constant-measure check; without it the call still reports unresolved home tables and binding-shape issues that don't need the live model.

Pass visual_id to narrow to a single visual; pass page to narrow to a specific page; both omitted scans the whole report.

Disable the auto K/M/B unit-scaling on card visuals (sets labelDisplayUnits=1 plus an explicit labelPrecision).

Plan or run an Excel workbook import into Power BI.

Execute a DAX or DMV query.

Execute a DAX query under a specific role context.

Export the currently active theme JSON from an extracted report.

Writes a copy of the theme referenced by activeTheme (or the last entry in themeCollection) to output_path. Useful for capturing the baseline theme before customising it.

Generate a Markdown correction report aggregating all analysis tools.

Output sections: model overview, star-schema verdict, circular dependency scan, optional rubric scoring, audit issues. Writes to output_path and returns the path plus an inline summary.

Export the full model as JSON, optionally writing it to disk.

Export model, DAX, layout, binding, and score validation as JSON.

Render a compact markdown snapshot of the model — tables, columns, measures, relationships — ready to paste into an LLM system prompt so the LLM can author DAX with full schema context in one round-trip.

Sections:

• # Model: <name>

• one ## <Table> per table with Columns: and (optionally) DAX Measures: lines

• ## Relationships with A[X] → B[Y] (cardinality, active) rows

Output is truncated to max_chars (default 12 000) with a trailing note when truncation kicks in. Set include_dax=False to omit the measure expressions and stay terse.

Generate and execute smoke tests for DAX measures.

Read the M expression for a specific table partition.

Parse a .dax file and bulk-create measures.

Import an Excel workbook into Power BI tables in one call.

Validate measures, formats, and measure/column name collisions.

Detect overlaps, excessive whitespace, tiny visuals, and missing titles.

Optional knobs to silence noise on intentionally dense pages:

• ignore_warnings: list of warning types to drop (e.g. ["too_many_visuals", "visual_too_small", "missing_title", "excessive_whitespace", "layout_overloaded"]). Issues are never ignored — only warnings.

• only_pages: restrict the scan to a list of page display names / internal names. Use to lint just the new pages an LLM produced.

• max_visuals_per_page: override the default too_many_visuals threshold (defaults to MAX_VISUALS_PER_PAGE). Set high to effectively disable the warning without ignoring it.

List calculation groups and their items.

Return the catalogue of format-string presets.

Optional filter_substring is matched (case-insensitive) against each preset's name to narrow the result — useful when an LLM only needs the "percent_*" or "currency_*" subset.

List discovered Power BI Desktop instances without forcing a connection.

List all model measures.

List table partitions and their current source expressions.

List model relationships.

Return the repairable-error vocabulary used by pbi_repair_loop.

Each entry maps a stable error code to its severity, whether the loop can fix it automatically, and the spec-level repair instruction an LLM should apply when it cannot.

List all model roles with their members and table filters.

List the available scaffold templates with summary metrics.

Return the catalogue of built-in presets with summary metadata.

List model tables and columns.

List TMDL files in a Power BI Project semantic model definition folder.

Return calc-dependency graph rows (source → referenced object) from DISCOVER_CALC_DEPENDENCY.

Plan or run validated batch measure creation.

Run a compact model audit with recommendations for an agent.

Return a full model snapshot in a single call.

Return the most-recent N tool operations recorded by the connection manager (newest first).

Each entry: {ts, op, kind: "read"|"write", duration_ms, ok} plus error_type/error_code/error_message when ok is False. Use this to self-diagnose what just happened — e.g. an LLM can pull the last 5 calls after a failure to see which writes already landed.

Make data sources portable via a Power Query parameter.

Creates (or updates) an M parameter named parameter_name whose default value is file_path. Then rewrites every M partition that string-matches file_path so it calls File.Contents(<parameter_name>) instead of the hardcoded path. After the parameter is wired in, a collaborator can change the file location once via Power BI Desktop's Transform data → Manage parameters dialog without editing each query.

partitions: optional explicit list of "Table[/Partition]" to rewrite. By default every M-source partition that references file_path is rewritten.

Patch the modified Report/Layout back into the PBIX archive.

When force=True the call closes (and if necessary kills) Power BI Desktop so the PBIX can be overwritten. save_before_close (default True) sends Ctrl+S to every running PBI Desktop window via PostMessage before the kill, then waits up to 10 seconds for the PBIX mtime to change. This flushes any in-memory TOM mutations (measures, columns, role filters) that have not yet been persisted — without this, those changes are lost when the process is killed.

The save attempt is best-effort: it never raises, and the layout patch proceeds regardless of whether the save succeeded. The response includes save_attempt with telemetry so the caller can detect silent loss.

Create or replace a measure block in one table TMDL file.

Trigger Power BI Desktop to save the open PBIX (Ctrl+S in the UI).

The Tabular engine has no programmatic save — every TOM mutation lives in memory until the user presses Ctrl+S. This tool drives that key chord through Win32 keyboard injection on the connected Desktop instance's main window.

Hard gates (both required):

• The server process must have PBI_MCP_ALLOW_UI_AUTOMATION=1 set in its environment before launch.

• The caller must pass confirm=True per call.

Either gate failing returns a structured error without acting. The automation only sends Ctrl+S; no other key sequences are emitted.

Parameters

pbix_path: Optional. When provided, the call polls the file's modification timestamp for up to timeout_seconds after sending Ctrl+S, and reports the observed delta in the response. Without it the call returns immediately after key injection. confirm: Must be True. Refusing-by-default avoids accidental focus steals from other tools. timeout_seconds: Bound on how long to wait for pbix_path mtime to change. Clamped to [1, 60].

Plan a visual from a business-intent spec without touching the report.

intent keys (all optional unless a rule needs them): metric / metrics — 'Table.Measure' reference(s) dimension — 'Table.Column' categorical axis time — 'Table.Column' time axis (implies trend) breakdown — 'Table.Column' secondary split (legend/series) target — 'Table.Measure' reference or numeric goal comparison, trend, parts_of_whole, correlation, geographic, detail_table, many_categories, filter_control — boolean hints

Returns the chosen visual_type, the matching pbi_add_visual config, and a rationale explaining the rule that fired.

Read one TMDL file from a Power BI Project definition folder.

Trigger a model or table refresh.

Reload cached TOM schema from the server (cheaper than full reconnect).

Bulk-rewrite a hardcoded file or folder path inside every M partition.

Use when a workbook moves and queries break with DataSource.NotFound. Looks for old_path as a substring of each M-source partition expression and replaces it with new_path. Calculated/query-source partitions are skipped. dry_run=True returns the planned changes without writing.

Remove a member from a role, matching by MemberName (case-insensitive).

Rename a column. Callers are responsible for updating dependent DAX.

Rename a DAX measure. Callers must update downstream DAX expressions themselves.

Rename a table. Callers are responsible for updating dependent DAX expressions.

Detect → classify → auto-repair → re-verify loop for a report extract.

Each round scans visual bindings, applies the deterministic repairs (query-ref mismatches, measure home tables) when apply=True, saves, and rescans — until no repair is applied or max_rounds is reached. Gauge target consistency and double display-unit scaling are then checked on the converged layout; check_empty_visuals=True (requires a live connection) additionally probes every visual's data query.

The response's repairable_errors lists the residual issues in classified form, each with an llm_action telling the calling model how to fix its spec.

Run a complete QA scenario against the active model and optional extracted layout.

Create a starter PBIX from a named template.

Templates: blank (date table only), finance, sales, analytics. Optional theme_json_path is validated against the Power BI theme schema (size, key allowlist, colour format, URL-bearing values) and embedded in the generated file. Additional measures supplied via extra_measures are appended after the template's baseline pack.

Score dashboard quality across model, DAX, layout, and readability.

Aggregate scoring across multiple validators.

Each criterion is a dict with:

• id (str): unique identifier

• label (str): human description

• check (str): one of star_schema, no_circular_deps, power_query_steps, missing_visuals, measure_exists

• weight (float, default 1.0)

• params (dict): check-specific parameters

Returns per-criterion verdicts plus a weighted total score in [0, 1].

Set the DataType (and optionally FormatString) of an existing column.

Works for any column kind (source, calculated, calculated table column). Use when Power Query type hints (Int64.Type etc.) are overridden by PBI's downstream inference and the column ends up as the wrong type.

data_type accepts standard TOM names (Int64, Decimal, Double, String, DateTime, Boolean, Currency, Binary, Variant).

Batch-apply format strings to measures or columns.

Write or update an M expression on a table partition.

Set (or remove when filter_expression is None/empty) the RLS DAX filter on a table for a role.

Set the fill colour for a single series of a chart visual.

Power BI stores per-series overrides inside singleVisual.objects.dataPoint as additional list entries with an id selector pinned to the target series' measure or column. The bare defaultColor property only affects series that do not have an explicit override — using it on a multi-series chart paints every series the same colour.

Specify the target series by series_index (0-based across the visual's projections, in role order) or series_name (matches the queryRef or the underlying measure / column Property name). Optional role narrows the lookup to a specific projection role (e.g. "Y", "Values").

Set / reset formatting properties on a visual's singleVisual.objects[<object_name>][0].properties.

Parameters

extract_folder, page, visual_id, object_name: Identify the target. object_name is the Power BI object key ('title', 'dataPoint', 'labels', 'background', 'general', etc.). properties: {property_name: value} to set. Values are encoded as Power BI literals via the type hint in property_types. property_types: {property_name: type_hint}. Valid hints:

- ``auto`` (default) — infer from Python type
- ``bool`` — booleans
- ``int`` — integers (alias: ``integer``)
- ``decimal`` — floats / numerics (alias: ``float``, ``number``)
- ``text`` — strings (alias: ``string``)
- ``color`` — hex strings ``"#RRGGBB"`` (alias: ``fill``, ``hex``,
  ``rgb``); a previously-encoded ``{"solid": {"color": ...}}``
  object is also accepted and unwrapped automatically
- ``raw`` — pass the value untouched (advanced)

Type names are case-insensitive. Unknown hints raise with the
full list.

reset_properties: Optional list of property names to delete from the visual's property bag. Use this to revert a property to Power BI's default — passing an empty string would leave the key set to a blank value instead.

Examples

Set a title (text):

pbi_set_visual_format_property(
    extract_folder, page, visual_id,
    object_name="title",
    properties={"text": "Sales", "show": True},
    property_types={"text": "text", "show": "bool"},
)

Set a fill color (single-series default):

pbi_set_visual_format_property(
    ...,
    object_name="dataPoint",
    properties={"defaultColor": "#4472C4"},
    property_types={"defaultColor": "color"},
)

Reset a property to Power BI's default:

pbi_set_visual_format_property(
    ...,
    object_name="title",
    reset_properties=["text"],
)

Single-call self-diagnostic for stability and dependency status.

Read-only. Skips any TOM/ADOMD probe gracefully when no connection is active. Use as a preflight from any LLM agent: one call answers "can I talk to Power BI right now?" without juggling connect / list / model_info.

Execute a DAX query and return result rows with timing diagnostics.

Update properties of an existing relationship (cardinality, direction, is_active, name).

Update an existing visual's field bindings without removing and recreating it. Modes:

• projections: full replacement of all roles. dict keyed by role name (e.g. "Category", "Y", "Values"); each value is a list of field references ("Table.Column" for columns or bare measure names).

• add_to_role / remove_from_role: incremental edits to specific roles. Same value shape. Roles that end up empty after a remove are dropped from projections.

projections is mutually exclusive with the incremental params. Roles are validated against VISUAL_FIELD_ROLES[visual_type]; field references are validated against the live model when manager is supplied. The prototypeQuery is rebuilt from the new reference set so Power BI Desktop renders the visual correctly. dry_run=True runs every check but skips the layout disk write.

Parse-check a DAX expression by running a zero/one-row probe and catching errors.

kind='scalar' wraps the expression with EVALUATE ROW("v", ). kind='table' wraps the expression with EVALUATE TOPN(0, ).

semantic=True additionally checks every Table[Column] / [Measure] reference against the live model index and heuristically flags a percent-shaped format_string on a scalar-money expression — the response then carries a semantic block (see pbi_validate_dax_semantic_tool).

Validate a DAX boolean filter expression before visual probes.

Audit the model for common issues: empty expressions, missing format strings, orphan tables, duplicate measure names.

Validate that a patched PBIX still contains a readable, persistent report layout.

Open a PBIX in Power BI Desktop and scan for visible repair-error signals.

use_windows_ocr defaults to False because the underlying screenshot captures the entire primary desktop, not just the Power BI window. The OCR helper now returns only the matched signal labels and a length — never raw recognized text — so screen contents from other applications cannot leak through the response.

Verify that a Power Query (M) expression contains expected step patterns.

Each entry in expected_steps is treated as a substring (or regex if it starts with re:) that must appear at least once in the M expression. Useful for grading exercises: e.g. checking that a postal-code column has been left-padded to 5 chars, or that rows with null customer ids are filtered out.

Validate relationship cardinality, direction, duplicates, and ambiguity before creation.

Confirm a model follows star schema topology.

Heuristic: a fact table participates as the many-side in ≥1 relationship, a dimension table participates as the one-side. Tables that are both are flagged as bridge tables. Direct dimension-to-dimension relationships are flagged as snowflake violations. Fact tables wired to other facts are flagged as fact-to-fact (constellation).

Optional fact_table_hints lets callers force-tag tables as facts (matched case-insensitively); useful when a fact table has no incoming relationships yet because the model is being built incrementally.

Dry-run validation of a user-supplied theme JSON file.

Returns the parsed payload size, any schema issues (errors + warnings), and the list of allowed top-level keys for reference. Performs no disk write and does not require an extract folder.

Alias-level visual binding validation with clearer tool naming.

Create or overwrite one TMDL file inside a Power BI Project definition folder.