Metadata-Version: 2.4
Name: pbix-atlas
Version: 0.3.0
Summary: Universal lineage graph for Power BI (.pbix) files, from physical source to report display.
Project-URL: Homepage, https://github.com/fabienfrfr/pbix-atlas
Project-URL: Issues, https://github.com/fabienfrfr/pbix-atlas/issues
Author-email: fabienfrfr <fabien.furfaro@gmail.com>
License: MIT
License-File: LICENSE
Keywords: data-lineage,dax,networkx,pbix,power-bi,power-query
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: networkx>=3.0
Requires-Dist: pandas>=2.0
Requires-Dist: pathspec>=1.1.1
Requires-Dist: pbixray>=0.15
Requires-Dist: pygraphviz>=2.0.1
Requires-Dist: scipy>=1.15.3
Provides-Extra: api
Requires-Dist: fastapi>=0.115; extra == 'api'
Requires-Dist: fastmcp<4,>=2.0; extra == 'api'
Requires-Dist: python-dotenv>=1.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'api'
Provides-Extra: codegen
Requires-Dist: plotly>=5.20; extra == 'codegen'
Requires-Dist: requests>=2.31; extra == 'codegen'
Requires-Dist: sqlalchemy>=2.0; extra == 'codegen'
Requires-Dist: vizro>=0.1.59; extra == 'codegen'
Provides-Extra: dev
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: fastmcp<4,>=2.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: marimo>=0.23; extra == 'dev'
Requires-Dist: plotly>=5.20; extra == 'dev'
Requires-Dist: pytest-bdd>=7.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: pyvis>=0.3.2; extra == 'dev'
Requires-Dist: requests>=2.31; extra == 'dev'
Requires-Dist: sqlalchemy>=2.0; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'dev'
Requires-Dist: vizro>=0.1.59; extra == 'dev'
Description-Content-Type: text/markdown

# pbix-atlas

<!-- mcp-name: io.github.fabienfrfr/pbix-atlas -->

Universal lineage graph for Power BI `.pbix` files: source to visual field in one traversable graph.

```
source (HTTP, OData, SQL, file...) --> Power Query (M)
    --> column / calculated column --> measure (DAX)
        --> field displayed in a report visual
```

## Install

```bash
pip install pbix-atlas
# or
uv add pbix-atlas
```

## Quick start

```python
from pbix_atlas import LineageGraphBuilder, upstream, downstream, print_tree, find_nodes

graph = LineageGraphBuilder().build("my_report.pbix")

find_nodes(graph, "customer_name")
print_tree(graph, "visual_field::my_report.pbix::Page1::16::customer_name", direction="upstream")
print_tree(graph, "source::odata::example.com/odata/", direction="downstream")
```

## Export

```python
from pbix_atlas import export_graphml, export_nodes_csv, export_edges_csv, graph_summary

graph_summary(graph)                       # {'query': 70, 'column': 183, ...}
export_graphml(graph, "lineage.graphml")   # Gephi / yEd
export_nodes_csv(graph, "nodes.csv")
export_edges_csv(graph, "edges.csv")
```

## Codegen — standalone Python pipeline

Generates a single Python file reproducing a report's full chain: source → extraction → Power Query → semantic model → Vizro dashboard. The M source is executed at runtime by the built-in interpreter, not pattern-matched. Unimplemented functions raise `MRuntimeError` (no silent stubs).

```bash
pip install "pbix-atlas[codegen]"
pbix-atlas-codegen my_report.pbix -o pipeline.py
```

```python
from pbix_atlas import generate_python_pipeline
generate_python_pipeline("my_report.pbix", "pipeline.py")
```

## HTTP API / MCP server

```bash
uv sync --extra api
uv run pbix-atlas    # http://127.0.0.1:8080
```

- REST: `POST /graphs`, `/search`, `/upstream`, `/downstream`, `/tree`, `/export`, `/codegen`
- MCP (streamable HTTP): `http://127.0.0.1:8080/mcp/`
- Env vars: `PBIX_LINEAGE_HOST`, `PBIX_LINEAGE_PORT`

## Architecture

| Module | Responsibility |
|---|---|
| `models.py` | Node/edge types and shared data structures |
| `sources.py` | Physical source detection (configurable patterns) |
| `pbix_model.py` | Adapter isolating from `pbixray` |
| `m_lexer.py` / `m_parser.py` | Built-in M tokenizer and parser |
| `m_interpreter.py` | M runtime interpreter + stdlib |
| `dax_translate.py` | DAX → Python (supported subset) |
| `dax.py` | DAX reference parsing |
| `mquery.py` | Power Query dependencies (table-level) |
| `layout.py` | Internal `Report/Layout` format parsing |
| `graph_builder.py` | Orchestrator: builds the `networkx.DiGraph` |
| `navigation.py` | Upstream/downstream traversal, search, export |
| `codegen.py` | Python pipeline code generation |
| `api/app.py` | FastAPI + MCP mount ([FastMCP](https://gofastmcp.com/)) |

## Sample files

- [Retail Analysis Sample PBIX](https://download.microsoft.com/download/9/6/D/96DDC2FF-2568-491D-AAFA-AFDD6F763AE3/Retail%20Analysis%20Sample%20PBIX.pbix) (Microsoft)
- [Sales & Returns Sample v201912](https://github.com/microsoft/powerbi-desktop-samples/raw/refs/heads/main/Sample%20Reports/Sales%20%26%20Returns%20Sample%20v201912.pbix) (Microsoft)

## Development

```bash
uv sync --extra dev
uv run pytest
uv build
```
