Metadata-Version: 2.5
Name: tableau-inspector
Version: 0.10.0
Summary: Analyze Tableau workbooks (.twb, .twbx) for common issues before publishing.
Author: Joshua Bowen
License: MIT License
        
        Copyright (c) 2026 Joshua Bowen
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: linter,static-analysis,tableau,twb,twbx
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: server
Requires-Dist: keyring; extra == 'server'
Requires-Dist: tableauserverclient; extra == 'server'
Description-Content-Type: text/markdown

# tableau-inspector (Python)

Local-first CLI that statically analyzes Tableau workbooks (`.twb` / `.twbx`) for common issues —
dev-only DB connections, hidden worksheets, unused calculations/parameters, duplicate calculations,
default filters, blank dashboard titles, missing captions, duplicate field aliases — before you
publish. Everything is parsed from the workbook's embedded XML.

An optional AI assistant (`ask`, `explain`, `summarize`, `docs --ai`) can explain calculations,
summarize dashboards, and answer questions in plain English. It sends only already-extracted
metadata (never raw XML, never live Tableau data) to a configured AI provider — a local Ollama
instance by default, so workbook metadata stays on your machine. Every other command makes no
network calls at all.

This is a Python port of the Node.js `tableau-inspector` CLI, with the same functionality and
zero runtime dependencies (stdlib only) -- the AI provider layer is implemented with stdlib
`urllib`, so this holds even with the assistant enabled.

## Install

```bash
pip install -e .
```

## Quick start

```bash
# Lint a workbook for common publishing issues
tableau-inspector analyze workbook.twbx

# Generate a self-contained interactive HTML explorer (overview, lineage, calculations, health)
tableau-inspector explore workbook.twbx

# Trace what a field/calculation depends on and what depends on it
tableau-inspector lineage workbook.twbx --field "Customer Segment"

# Search fields, calculations, dashboards, worksheets, filters, parameters, and datasources
tableau-inspector search workbook.twbx "profit"
tableau-inspector search workbook.twbx "DATEDIFF" --formula
tableau-inspector search workbook.twbx "sales" --type field

# Diff two versions of a workbook
tableau-inspector compare old.twbx new.twbx

# Ask a question about a workbook (requires a running Ollama instance)
tableau-inspector ask workbook.twbx "What does Profit Margin calculate?" --model llama3.1

# Explain a calculation, field, or dashboard in plain English -- runs a deterministic
# investigation (formula, dependencies, lineage, usage) before asking the AI to explain it
tableau-inspector explain workbook.twbx --calculation "Profit Margin" --model llama3.1
tableau-inspector explain workbook.twbx --field "Customer Segment" --model llama3.1
tableau-inspector explain workbook.twbx --dashboard "Executive Dashboard" --model llama3.1 --level quick

# Summarize a dashboard's purpose, contents, filters, parameters, and key calculations
tableau-inspector summarize workbook.twbx --dashboard "Executive Dashboard" --model llama3.1

# Generate documentation with AI-written summaries and calculation explanations woven in
tableau-inspector docs workbook.twbx --ai --model llama3.1

# Point any AI command at a local business-context file for domain knowledge (custom metric
# definitions, fiscal-calendar notes, etc.) -- read locally only, never uploaded or persisted
tableau-inspector explain workbook.twbx --calculation "Profit Margin" --model llama3.1 --context company-context.md

# Lint (analyze + check-filters + compare), then git commit and push a workbook change,
# with an AI-generated commit message
tableau-inspector push workbook.twb --model llama3.1
```

Every command also supports `--json` for machine-readable output, and `analyze`/`compare` support
`--html` for a shareable, self-contained HTML report.

## AI assistant

`ask`/`explain`/`summarize`/`docs --ai` require a model name via `--model`, the
`TABLEAU_INSPECTOR_AI_MODEL` environment variable, or (for a non-default provider)
`--provider`/`TABLEAU_INSPECTOR_AI_PROVIDER`. The default provider is a local
[Ollama](https://ollama.com) instance at `http://localhost:11434` (override with `--ollama-host` /
`TABLEAU_INSPECTOR_OLLAMA_HOST`). Start Ollama and pull a model before using these commands:

Every AI command also accepts `--context <path>` (or `TABLEAU_INSPECTOR_CONTEXT_FILE`) to inject
a local business-context file — `.md`, `.txt`, or `.json`, up to 20KB — as supplementary domain
knowledge in the AI prompt. It's read locally and sent only to the configured AI provider, never
uploaded or persisted, and it never overrides actual workbook metadata.

```bash
ollama serve
ollama pull llama3.1
```

## Documentation

See [USAGE.md](USAGE.md) for the full command reference (every flag, exit codes, AI provider
setup, and example workflows), or run `tableau-inspector --help` / `tableau-inspector <command>
--help` for the same option reference from the CLI itself.

## License

MIT © Joshua Bowen
