Metadata-Version: 2.4
Name: cepheus-navis
Version: 5.12.11
Summary: Airgapped Tableau-to-Power BI conversion tool with proven calculation correctness and signed governance artifacts
Author-email: Cepheus Engineering <navis@cepheusonline.com>
License: Proprietary
Project-URL: Homepage, https://www.cepheusonline.com/navis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=4.9
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: lark>=1.1
Requires-Dist: reportlab>=4.0
Requires-Dist: pypdf>=4.0
Requires-Dist: pyhanko>=0.25
Requires-Dist: cryptography>=41.0
Dynamic: license-file

# Cepheus Navis

Airgapped Tableau-to-Power BI conversion tool where every calculation translation is backed by a mathematical proof of correctness — the conversion is demonstrably correct, not just plausible.

Cepheus Navis reads a Tableau workbook (.twb / .twbx) and writes a Power BI Project (.pbip) — without connecting to any database or network. Signed audit trails, equivalence reports, and pre-conversion analysis are delivered as tamper-evident PDFs.

---

## Key capabilities

| Capability | Details |
|---|---|
| Airgapped operation | Core conversion runs with no network access; structure is migrated, not data |
| Proven calculation correctness | Every DAX formula is tested against actual Tableau output — proven equivalence, not approximate translation |
| Pre-conversion analysis | Analysis report shows automation rate, complexity ratings, and degradation summary per workbook — before you convert |
| Signed audit trails | Per-calculation translation records with original formulas and DAX equivalents — tamper-evident PDFs with embedded JSON |
| Calculation coverage | Aggregations, LOD expressions (FIXED, INCLUDE, EXCLUDE), table calculations, IF/CASE/IIF, string/date/math functions |
| Consult mode | Assess an existing Power BI conversion (from any source) against Navis's validated reference — per-calculation verdicts without exposing reference DAX |
| Filter migration | Categorical, range, date, and Top N filters translated to Power BI equivalents |
| Data model | Tables, columns, and data types emitted as TMDL semantic model definitions |
| Visual types | Bar, line, area, pie, scatter, map, table, and more |

---

## Requirements

- Python 3.9 or later
- A licensed Cepheus Navis installation (see Licensing below)

---

## Installation

```bash
pip install cepheus-navis
```

Verify the installation:

```bash
cepheus-navis --version
```

---

## Quick start

Every command takes a `spec.toml` project file as its first argument. Create one for your project and fill in the paths. CLI flags override spec values when provided.

### 1. Analyze your workbooks

```bash
cepheus-navis analyze spec.toml
```

Scans the directory for Tableau workbooks and produces a License Request PDF — automation rate, per-workbook complexity ratings, degradation summary, and SHA-256 checksums. Submit it to navis@cepheusonline.com to obtain a license file.

### 2. Verify your license

Add the license path to your `spec.toml`:

```toml
[verify-license]
license_file = "license.json"
path = "C:/Tableau/Workbooks"
```

Then verify:

```bash
cepheus-navis verify-license spec.toml
```

The output shows `VALID`, `MISMATCH`, or `UNLICENSED` for each workbook. If a file shows `MISMATCH`, it was modified since analysis — re-run `analyze` and request a new license.

### 3. Convert

```bash
cepheus-navis convert spec.toml
```

### 4. Consult — assess an existing conversion

Already have a Power BI conversion from another tool or hand-coded? Compare it against Navis's validated reference. Requires a consult licence.

Add the consult section to your `spec.toml`:

```toml
[consult]
path    = "C:/Tableau/Workbooks/Sales.twbx"
against = "C:/PowerBI/SalesProject.pbip"
output  = "C:/Reports/consult-output"
```

Then run:

```bash
cepheus-navis consult spec.toml
```

The Consult Report tells you which of your DAX calculations are correct, which have structural issues, and which Tableau calculations are missing from your project — assessed against a proven reference. Requires a PBIP project folder — `.pbix` files must be saved as Power BI Projects first.

---

## What to expect

Navis provides verified semantic equivalence for calculations, 
data structures, and data model elements. Confidence levels 
(Exact, Composed, Deterministic, Degraded) are documented in 
the Conversion Evidence Capsule.

Dashboard layout and chart types are converted on a best-effort 
basis. Visual formatting — colours, fonts, padding, reference 
lines, tooltips, conditional formatting, etc. — requires human 
review and adjustment in Power BI Desktop.

Calculations: verified. Visuals: best-effort, human review required.

---

## Output structure

```
SalesDashboard/
├── SalesDashboard.pbip                # Entry point
├── SalesDashboard.Report/
│   ├── definition.pbir
│   └── report.json
├── SalesDashboard.SemanticModel/
│   ├── definition.pbism
│   └── definition/
│       ├── model.tmdl
│       ├── database.tmdl
│       ├── tables/
│       │   └── Orders.tmdl            # Your measures (DAX) live here
│       └── cultures/
│           └── en-US.tmdl
└── SalesDashboard_CEC.zip             # Evidence Capsule (see below)
```

---

## Licensing

Cepheus Navis uses a checksum-based license that ties a specific license file to specific workbook files.

```
analyze  →  submit report  →  receive license  →  convert
```

The `analyze` command produces a PDF containing SHA-256 checksums of your workbooks. Cepheus issues a license that approves exactly those files. The `convert` command validates the checksums before running the pipeline. This prevents accidental conversion of modified or untested workbooks.

---

## Governance artifacts

Two signed artifacts are produced by the `convert` command. They cannot be disabled.

**Conversion Report PDF** — produced for each workbook:
- Every calculation with its original Tableau formula and converted DAX
- Worksheet-to-page mapping with visual type translations
- Degradation addendum listing features that need manual attention
- Data model summary (tables, columns, data types)

**Evidence Capsule** (`_CEC.zip`) — tamper-evident conversion record:
- The conversion report PDF
- Original workbook and generated Power BI project files
- Machine-readable audit log of every step the tool took
- Cryptographic hash chain linking inputs → outputs → proofs → audit records

All PDFs are tamper-evident with embedded JSON attachments and integrity signatures.

---

## Further reading

The complete How-To Guide is bundled with the package. After installation:

```bash
cepheus-navis howto
```

This opens the full guide in your browser — installation, spec.toml configuration, the three-step workflow, governance artifacts, digital signing, audit logs, and troubleshooting. Works offline.
