twilize 0.13.0__tar.gz

twilize-0.13.0/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.venv
+venv
+env
+__pycache__
+*.pyc
+node_modules
+extension/frontend/node_modules
+extension/frontend/dist
+.env
+*.log
+output/
+tests/
+docs/

twilize-0.13.0/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+*.log
+*.logs
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Node
+node_modules/
+package-lock.json
+
+# Test output
+output/
+
+# Temp files
+temp_template.twb
+test_api.py
+test_env.py
+example_data.csv
+
+# Large/binary project files
+backup/
+dashboard/
+*.twbx
+*.hyper
+!src/cwtwb/references/*.hyper
+*.twbr
+tmp/
+templates/migrate/* - migrated to *.twb
+templates/migrate/migration_report.json
+templates/migrate/field_mapping.json
+examples/migrate_workflow/* - migrated to *.twb
+examples/migrate_workflow/* - migrated.twb
+examples/migrate_workflow/migration_report.json
+examples/migrate_workflow/field_mapping.json
+examples/migrate_workflow/prompt.txt

twilize-0.13.0/CHANGELOG.md

@@ -0,0 +1,300 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.16.0] - 2026-03-19
+
+### Fixed
+
+- **`FieldRegistry.remove()` missing**: `TWBEditor.remove_calculated_field()` and its `remove_calculated_field` MCP tool called `self.field_registry.remove()`, but `FieldRegistry` only defined `unregister()`. Added the missing `remove()` method; the MCP tool now works correctly instead of raising `AttributeError`.
+- **Dual-axis pane secondary ID mismatch**: `DualAxisChartBuilder` wrote `id="3"` for the secondary pane in both horizontal and vertical configurations, while all test assertions and internal lookups expected `id="2"`. Changed pane_2 id to `"2"` in both the same-measure (lollipop/donut) and different-measure (combo) branches.
+- **`format_capability_catalog()` missing `level_filter` parameter**: The function signature accepted no arguments, but the capability registry design and test suite expected an optional `level_filter: str` parameter to restrict output to a single level (e.g. `"core"`). Added the parameter; calling without it preserves the existing full-catalog behavior.
+- **`inspect_target_schema` crashes on non-Excel paths**: The MCP tool passed any path directly to `xlrd.open_workbook()`, raising `FileNotFoundError` or `XLRDError` for `.csv`, non-existent files, or unsupported formats. Added an extension check up-front and a `try/except` fallback; both now return a readable `"Unsupported…"` string instead of an exception.
+- **`analyze_twb` missing Capability gap section**: `analyze_twb` returned only `report.to_text()`, omitting the decision-oriented gap summary that `diff_template_gap` produces separately. The tool now appends `report.to_gap_text()` so a single `analyze_twb` call includes both the capability catalog and the gap triage.
+
+## [0.15.0] - 2026-03-18
+
+### Added
+
+- **XSD schema validation** against the official Tableau TWB XSD (2026.1), vendored at `vendor/tableau-document-schemas/`:
+  - `TWBEditor.validate_schema()` — validates the in-memory workbook without saving first; returns a `SchemaValidationResult` with `valid`, `errors`, `schema_available`, and `to_text()` summary.
+  - `validate_workbook` MCP tool — validates the current open workbook (in memory) or any `.twb`/`.twbx` file on disk by path. Errors are reported as informational; Tableau itself occasionally generates workbooks that deviate from the schema.
+  - `validate_against_schema(root)` — public SDK function in `twilize.validator`, accepts an lxml `_Element` and returns `SchemaValidationResult`.
+  - `SchemaValidationResult` exported from the top-level `twilize` package.
+  - Two missing XSD imports (`http://www.tableausoftware.com/xml/user` and `http://www.w3.org/XML/1998/namespace`) resolved via local stub XSD files written to `vendor/tableau-document-schemas/schemas/2026_1/` at first use; schema is loaded once and cached for the process lifetime.
+
+## [0.14.0] - 2026-03-17
+
+### Added
+
+- **`.twbx` (Packaged Workbook) support**: `TWBEditor` now reads and writes Tableau Packaged Workbook files transparently.
+  - **Open**: `TWBEditor("file.twbx")` and `TWBEditor.open_existing("file.twbx")` unzip the archive, locate the embedded `.twb`, and parse it in-memory. The source ZIP path and inner filename are recorded for later re-packing.
+  - **Save as `.twbx`**: `editor.save("output.twbx")` serializes the updated XML and re-packs it into a new ZIP, carrying over all bundled assets (`.hyper` data extracts, images, etc.) from the source `.twbx` automatically.
+  - **Save as `.twb` from a `.twbx` source**: `editor.save("output.twb")` extracts just the workbook XML, discarding the packaging.
+  - **Plain `.twb` → `.twbx`**: any `.twb`-sourced workbook can be packaged by saving with a `.twbx` extension; the result is a single-entry ZIP containing the workbook XML.
+  - MCP tools `create_workbook`, `open_workbook`, and `save_workbook` all support `.twbx` paths with no changes to call signatures.
+- **`tests/test_twbx_support.py`**: 25 pytest cases covering open, round-trip save, extract/image preservation, plain-TWB-to-TWBX conversion, modify-and-resave, and MCP tool integration.
+
+## [0.13.0] - 2026-03-17
+
+### Added
+
+- **Rich-text `label_runs` in `configure_chart`**: Multi-style labels built from a list of run dicts. Each run supports `text` (literal string), `field` (field expression → `<field_ref>` CDATA), `prefix`, and per-run font attributes (`fontname`, `fontsize`, `fontcolor`, `bold`, `fontalignment`). Use `"\n"` as text to insert a paragraph separator. Pass `"fontalignment": None` to suppress the default alignment attribute. Enables KPI cards with two-line labels, dynamic titles with inline field values, and branded separators.
+- **14 new `configure_worksheet_style` options**:
+  - `hide_col_field_labels` / `hide_row_field_labels` — hide column and row field label headers in table/cross-tab views
+  - `hide_droplines` — remove drop lines from mark tooltips
+  - `hide_table_dividers` — remove row/column divider lines in cross-tab views
+  - `hide_reflines` — hide reference lines
+  - `disable_tooltip` — disable tooltip entirely (`tooltip-mode='none'`)
+  - `pane_cell_style: dict` — pane-level cell text alignment, e.g. `{"text-align": "center", "vertical-align": "center"}`
+  - `pane_datalabel_style: dict` — pane-level data label font family, size, and color
+  - `pane_mark_style: dict` — pane-level mark color, stroke, transparency, and size (0.0–1.0 scale via `"size"` key)
+  - `pane_trendline_hidden: bool` — hide trendline in pane style
+  - `label_formats: list[dict]` — per-field label style (font, color, orientation, display toggle)
+  - `cell_formats: list[dict]` — per-field table cell style
+  - `header_formats: list[dict]` — per-field header height/width
+  - `axis_style: dict` — global tick color plus per-field axis display and height control
+- **`mark_color_1` in `configure_dual_axis`**: Explicit hex color for primary-axis marks, symmetric with the existing `mark_color_2`. Useful for pairing a gray bar (`mark_color_1`) against a blue target GanttBar (`mark_color_2`).
+- **`color_map_1` in `configure_dual_axis`**: Datasource-level palette mapping for the primary-axis `color_1` field, using the same mechanism as `configure_chart(color_map=...)`.
+- **`default_format` in `add_calculated_field`**: Optional Tableau number format string written as `default-format` on the column XML, e.g. `'c"$"#,##0,.0K'`.
+- **`color_map` in `configure_dual_axis(extra_axes=[...])`**: Custom palette for `:Measure Names` when used as `"color"` on an extra axis. Each bucket is mapped to a hex color via a datasource-level `<encoding>` element.
+- **`show_title` in dashboard layout nodes**: Pass `show_title: false` in a layout zone dict to suppress the worksheet title bar inside a dashboard zone.
+- **Expanded test suite — 7 new test modules**:
+  - `test_worksheet_style.py` — all 18 `configure_worksheet_style` options (hide flags, background, pane styles, per-field formats, axis style)
+  - `test_label_runs.py` — text runs, field-ref runs, newline separator, font styling, prefix, fontalignment suppression, KPI card and dynamic title patterns
+  - `test_dual_axis_basic.py` — horizontal/vertical dual-axis combos, shared axis, color encoding, filters
+  - `test_dual_axis_advanced.py` — `mark_color_1/2`, `color_map_1`, `reverse_axis_1`, `hide_zeroline`, synchronized axis, `show_labels`, `size_value_1/2`
+  - `test_dashboard_action_types.py` — highlight action (`tsc:brush`), field-captions param, multiple coexisting actions, error handling (unsupported type, unknown dashboard)
+  - `test_mcp_tools.py` — `remove_calculated_field` (add/remove/re-add cycle), connection MCP wrappers, `inspect_target_schema`, `list_capabilities`, `analyze_twb`
+  - `test_template_datasource_structure.py` — Superstore template structural sanity: column count, connection class, datasource-dependencies
+- **`tests/README.md`**: Full test suite documentation — run instructions, file index grouped by coverage area, function-to-test mapping table, known gaps.
+
+### Changed
+
+- **Examples reorganized**: Scripts moved from `examples/` root into `examples/scripts/` with consistent `demo_` prefix naming. `examples/README.md` updated with a new 7-script progression table and expanded Showcase Projects section.
+- **Exec Overview example refined**: Dashboard header updated to 2023, KPI cards use `pane_cell_style` for center alignment, `show_title: false` on Sales by Sub-Category worksheet, spacer zone added for axis alignment.
+
+## [0.12.0] - 2026-03-13
+
+### Added
+- **Bundled Hyper Extracts**: `Sample - EU Superstore.hyper` and `Sample _ Superstore.hyper` are now included in `src/twilize/references/` and distributed with the wheel. `hyper_and_new_charts.py` and `build_exec_overview.py` no longer require a cloned repository.
+- **Progressive Examples**: All scripts in `examples/scripts/` (5 steps, Beginner → Advanced) and prompts in `examples/prompts/` (10 steps, Beginner → Advanced) now carry explicit step numbers and difficulty labels. `examples/README.md` rewritten with a Quick Start section and full progression tables.
+
+### Fixed
+- **Packaging**: Removed redundant `artifacts` declarations from `pyproject.toml`. All non-Python files under `src/twilize/` are git-tracked and included in the wheel automatically via `packages = ["src/twilize"]`.
+- **`.gitignore`**: Added `!src/twilize/references/*.hyper` exception so bundled Hyper files are tracked by git and always present at wheel build time.
+- **Examples — zero external dependencies**: All scripts in `examples/scripts/` and prompts in `examples/prompts/` updated to use `TWBEditor("")` / `create_workbook("")` (built-in default template) instead of hard-coded paths to `templates/twb/superstore.twb`. All work after a plain `pip install twilize`.
+
+## [0.11.0] - 2026-03-13
+
+### Added
+- **Table Calculation Fields**: `add_calculated_field` now accepts a `table_calc` parameter (e.g. `table_calc="Rows"`) that writes a `<table-calc ordering-type="..."/>` child inside the `<calculation>` element, enabling `RANK_DENSE`, `RUNNING_SUM`, `WINDOW_AVG`, and all other Tableau table calculation functions to work correctly in the generated workbook.
+- **Table Calc Column Instances**: `_setup_datasource_dependencies` in `builder_base` now automatically propagates a `<table-calc ordering-type="Columns"/>` element to any `<column-instance>` whose source column contains a table-calc calculation, matching the pattern Tableau uses for rank and running calculations.
+- **Multi-field Label Support**: `configure_chart` now accepts `label_extra: list[str]` to bind multiple `<text>` encodings to a single mark, enabling combined text labels such as a sales figure plus a state name in one cell.
+- **Row Dimension Label Hiding**: `configure_worksheet_style` now accepts `hide_row_label: str` to suppress the header column that Tableau renders for a rows-shelf dimension (adds `<style-rule element="label"><format attr="display" ... value="false"/></style-rule>`).
+- **Donut Chart via `extra_axes`**: Pie panes in `configure_dual_axis(extra_axes=[...])` now automatically receive a `<size column="[Multiple Values]"/>` encoding when `measure_values` is present, completing the standard Tableau donut chart pattern without manual intervention.
+- **Non-traditional Pie Mark via `BasicChartBuilder`**: `configure_chart(mark_type="Pie")` without `color` or `wedge_size` now routes through `BasicChartBuilder` instead of `PieChartBuilder`, allowing a Pie mark to display a label (e.g. a rank number) on a dimension-shelved view while retaining full rows/sort/filter support.
+- **`selection-relaxation-disallow` on single-pane charts**: All charts built by `BasicChartBuilder` now set `selection-relaxation-option="selection-relaxation-disallow"` on the `<pane>` element, matching Tableau's default for filtered single-view worksheets and preventing click-interaction from relaxing Top N or categorical filters.
+
+### Fixed
+- **Measure Names filter ordering**: In `configure_dual_axis` with `extra_axes` containing `measure_values`, the Measure Names `<filter>` is now inserted into the `<view>` before Top N filters, matching the element order Tableau produces when creating these worksheets interactively.
+
+### Example
+- **Exec Overview Recreated** (`examples/superstore_recreated/`): Added `Rank CY` table calculation field; corrected `Top 5 Locations` to use Pie mark with Rank CY label; corrected `Top 5 Locations text` and `Sales by Sub-Category` to match reference workbook (donut size encoding, label style rules, filter order).
+
+## [0.10.0] - 2026-03-11
+
+### Fixed
+- **XML Schema Conformity**: Fixed strict DTD validation errors related to `<pane>` child element ordering (e.g., `<customized-label>` must precede `<style>`) and `<datasource>` element ordering.
+- **Customized Labels**: Fixed `<customized-label>` generation to correctly wrap dynamic template variables with physical `<` and `>` runs within the XML `<formatted-text>` nodes, complying with strict formatting limits.
+- **Object-Graph Relationship Wiping**: Completely rewrote the `set_hyper_connection` logic for multi-table connections. It now preserves table-level relational links by surgically updating individual pre-existing `<object-graph>/<relation>` attributes correctly matching object definitions instead of flattening them into an unmapped collection.
+
+### Added
+- **Charting Capabilities**: Added parameters `axis_fixed_range` to configure exact visual bounds on measures, `color_map` for granular dataset-level color palette assignments, `mark_sizing_off` to disable auto scaling, `customized_label` for rich template texts, and `text_format` for rapid formatting adjustments.
+- **Dashboard Enhancements**: Added support for explicit `"empty"` layout model objects acting as blank spacers within absolute sizing layouts.
+- **MCP Server Capabilities**: Exposed `configure_worksheet_style` tool expressly to cleanly edit gridlines and aesthetics independently of core configuration.
+
+## [0.9.0] - 2026-03-10
+
+### Added
+- **Unified Recipe Chart API**: Added `configure_chart_recipe` as the single MCP/server entrypoint for showcase recipes, covering `lollipop`, `donut`, `butterfly`, and `calendar` via one registry-driven dispatcher.
+- **Recipe Validation Coverage**: Added regression tests for unknown recipe rejection, required-argument validation, automatic prerequisite field creation, and full `all_supported_charts` showcase reconstruction through the unified recipe API.
+
+### Changed
+- **Recipe Tool Surface**: Replaced the old recipe-specific MCP tools with one `configure_chart_recipe` interface to keep the public API compact as more showcase patterns are added.
+- **Recipe Defaults**: Donut and Calendar recipes now auto-create their standard helper calculations (`min 0` and `Sales Over 400`) when those defaults are used and the fields are missing.
+- **Examples and Prompts**: Updated README, examples, skill docs, and the showcase MCP prompt to teach the unified recipe workflow instead of enumerating one tool per recipe chart.
+
+### Removed
+- **Recipe-Specific MCP Tools**: Removed `configure_lollipop_chart`, `configure_donut_chart`, `configure_butterfly_chart`, `configure_calendar_chart`, and `apply_calendar_chart_layout` from the public MCP/server API.
+
+## [0.8.0] - 2026-03-09
+
+### Added
+- **Capability Registry**: Added a shared capability catalog that classifies chart, encoding, dashboard, action, connection, and feature support into `core`, `advanced`, `recipe`, and `unsupported` tiers.
+- **TWB Gap Analysis**: Added `twb_analyzer.py` plus MCP tools `list_capabilities`, `describe_capability`, `analyze_twb`, and `diff_template_gap` so templates can be evaluated against the declared product boundary before implementation work begins.
+- **Hyper Example Coverage**: Added `tests/test_hyper_example.py` to lock in the Advent Calendar Hyper example's physical `Orders_*` table resolution via Tableau Hyper API.
+
+### Changed
+- **Product Positioning**: Updated the root README and example READMEs to describe `twilize` as a workbook engineering toolkit rather than a conversational analysis competitor.
+- **Chart Architecture**: Refactored chart handling into focused modules under `src/twilize/charts/`, including dispatcher, pattern mapping, routing policy, helpers, and a dedicated text builder while keeping the public `configure_chart` API stable.
+- **Dashboard Architecture**: Split dashboard orchestration, layout resolution, datasource dependency generation, and action creation into dedicated modules while keeping `DashboardsMixin` as a thin compatibility facade.
+- **Layout Architecture**: Split declarative layout computation and XML rendering into `layout_model.py` and `layout_rendering.py`, leaving `layout.py` as a compatibility export layer.
+- **MCP Architecture**: Split the MCP server implementation into `mcp/app.py`, `mcp/state.py`, `mcp/resources.py`, `mcp/tools_support.py`, `mcp/tools_layout.py`, and `mcp/tools_workbook.py`, with `server.py` now acting as a thin compatibility entry point.
+- **Advanced Hyper Example**: Updated `examples/hyper_and_new_charts.py` to prefer the Tableau Advent Calendar `Sample - EU Superstore.hyper` extract and resolve the physical `Orders_*` table name automatically.
+
+### Fixed
+- **Hyper Extract Selection**: The advanced Hyper example no longer picks the first bundled `.hyper` file opportunistically and instead targets the intended Superstore extract.
+- **Hyper Table Resolution**: The advanced Hyper example now resolves the real physical `Orders_*` table name instead of using an incorrect generic table name.
+
+## [0.7.0] - 2026-03-06
+
+### Added
+- **Agent Skills Workflow System**: Introduced 4 specialized skill files that provide expert-level guidance to AI agents during dashboard creation, inspired by Jeffrey Shaffer (Tableau Visionary Hall of Fame).
+  - `calculation_builder.md` — Phase 1: Parameters, calculated fields, LOD expressions
+  - `chart_builder.md` — Phase 2: Chart type selection, encodings, filter strategy
+  - `dashboard_designer.md` — Phase 3: Layout design, filter panels, interaction actions
+  - `formatting.md` — Phase 4: Number formats, color strategy, sorting, tooltips
+- **Skills MCP Resources**: Skills are exposed via MCP protocol as `twilize://skills/index` and `twilize://skills/{skill_name}`, allowing AI agents to load domain expertise on demand.
+- **Updated MCP Server Instructions**: Server instructions now prompt AI agents to read skills before each phase for professional-quality output.
+
+### Changed
+- **ROADMAP**: Updated `docs/ROADMAP.md` — marked completed P0 items (module refactor ✅, version sync ✅), added new Skills workflow section.
+- **Package Build**: Added `artifacts` config in `pyproject.toml` to ensure `.md` skill files are distributed with the PyPI wheel.
+
+## [0.6.0] - 2026-03-06
+
+### Added
+- **Runtime TWB Validator**: `save()` now automatically validates TWB XML structure before writing to disk. Fatal errors (missing `<workbook>`, `<datasources>`, `<table>`) raise `TWBValidationError` and block saving; non-fatal warnings are logged. Validation can be disabled via `save(path, validate=False)`.
+- **`map_fields` Parameter**: New parameter for `configure_chart(mark_type="Map", ...)` allowing users to specify additional geographic LOD fields (e.g. `map_fields=["Country/Region", "City"]`).
+- **TWBAssert DSL**: Chainable assertion API (`tests/twb_assert.py`) for structural TWB validation in tests, with 20+ assertion methods covering worksheets, encodings, filters, parameters, calculated fields, dashboards, and maps.
+- **Shared Test Fixtures**: Added `tests/conftest.py` with `editor` and `editor_superstore` pytest fixtures.
+- **Structure Test Suite**: 19 new tests in `tests/test_twb_structure.py` covering Bar, Line, Pie, Area, Map, KPI, Parameters, Calculated Fields, Dashboards, and Filters.
+- **Project Roadmap**: Added `docs/ROADMAP.md` with P0–P3 priority issues and feature plans.
+
+### Changed
+- **Module Architecture**: Refactored `twb_editor.py` (2083→375 lines) into Mixin classes:
+  - `charts.py` (ChartsMixin) — `configure_chart` and 9 chart helper methods
+  - `dashboards.py` (DashboardsMixin) — `add_dashboard` and dashboard actions
+  - `connections.py` (ConnectionsMixin) — MySQL and Tableau Server connections
+  - `parameters.py` (ParametersMixin) — parameter management
+  - `config.py` — shared constants and `_generate_uuid`
+- **Version Management**: `__init__.py` now dynamically reads the version from `pyproject.toml` via `importlib.metadata` instead of hardcoding it.
+- **API Exports**: `__init__.py` now exports `TWBEditor`, `FieldRegistry`, and `TWBValidationError`.
+- **Worksheet XML Structure**: Improved `add_worksheet` to generate proper `<panes>/<pane>/<view>` hierarchy, `<style>` element, and `<simple-id>` placement per Tableau XSD schema.
+
+### Fixed
+- **Error Handling**: Replaced 6 instances of `except Exception: pass` with specific exception types (`KeyError`, `ValueError`) and proper `logging` output across `twb_editor.py`, `layout.py`.
+- **Circular Import**: Extracted `REFERENCES_DIR` and path constants to `config.py`, eliminating circular imports between `twb_editor.py` and `server.py`.
+- **Redundant Imports**: Removed 4 function-level `import` statements (`re`, `copy`, `dataclasses.replace`) by consolidating them at module level.
+
+### Breaking Changes
+- **Map Charts**: `configure_chart(mark_type="Map")` no longer automatically adds `Country/Region` as an LOD field. Users must now explicitly pass `map_fields=["Country/Region"]` if needed.
+
+## [0.5.3] - 2026-03-05
+
+### Fixed
+- **Calculated Field Parsing**: Improved parameter replacement regex to safely handle both `[ParamName]` and `[Parameters].[ParamName]` formats, preventing double-prefixing and broken expressions.
+
+## [0.5.2] - 2026-03-05
+
+### Added
+- **Business Profitability Overview Prompt**: Added `examples/prompts/overview_business_demo.md` to demonstrate creating an interactive what-if profitability dashboard with parameters and dashboard actions.
+
+### Fixed
+- **Packaging Issues**: Pinned `hatchling<1.27.0` to workaround a `twine` metadata validation error related to `license-files` and fixed Windows encoding issues during package build.
+
+## [0.5.1] - 2026-03-04
+
+### Changed
+- **License**: Updated project license from MIT to AGPL-3.0-or-later.
+
+## [0.5.0] - 2026-03-02
+
+### Added
+- **Zero-Config Blank Templates**: The SDK and MCP server now come with a built-in `empty_template.twb` and a minimal `Sample - Superstore - simple.xls` dataset.
+- **Dynamic Connection Resolution**: When initializing `TWBEditor` without a `template_path`, it automatically resolves and rewrites the internal Excel connection to the runtime absolute path of the bundled sample dataset.
+- **Always-Valid Workbooks**: `clear_worksheets()` now guarantees the creation of at least one default worksheet (`Sheet 1`), ensuring generated TWB files are completely valid and openable in Tableau Desktop immediately upon creation.
+
+### Changed
+- **MCP Tool `create_workbook`**: The `template_path` parameter is now optional. When omitted, it boots up the zero-config blank template.
+- **XML Element Ordering Fix**: `add_worksheet` and `add_dashboard` now strictly enforce the Tableau XSD schema by smartly inserting XML nodes *before* `<windows>`, `<thumbnails>`, and `<external>` tags instead of appending them at the end.
+
+## [0.4.0] - 2026-02-28
+
+### Fixed
+- **Dashboard Sizing Bug**: Added `sizing-mode="fixed"` to the dashboard `<size>` element. This ensures that custom dimensions (width/height) specified in `add_dashboard` are correctly enforced by Tableau Desktop.
+
+### Added
+- **New Showcase Prompt**: Added `examples/prompts/demo_auto_layout4_prompt.md` in English, demonstrating complex nested layouts with fixed headers and KPIs.
+- **Enhanced Testing**: Added assertions to verify `sizing-mode` in `test_declarative_dashboards.py`.
+
+## [0.3.0] - 2026-02-28
+
+### Added
+
+- **Agentic UX Tool: `generate_layout_json`**:
+  - Introduced a dedicated MCP tool tailored for Language Models to handle complex dashboard layouts gracefully avoiding `EOF` (End of File) payload oversize crashes.
+  - Automatically wraps standard nested `layout` dicts inside the payload with a human-readable `_ascii_layout_preview`, persisting an easy-to-review design draft to local disk.
+  - Generates perfectly calculated XML `<zone>` absolute coordinates (in Tableau's 100,000 scale) for both relative weighting (`weight`) and exact sizes (`fixed_size`).
+- `TWBEditor.add_dashboard()` intelligent parsing:
+  - If given a file path, it now smartly unpacks the layout JSON, automatically extracting `"layout_schema"` and safely discarding extraneous metadata (like the ASCII diagram).
+- **Prompt Strategies (`demo_simple.md`)**:
+  - Updated the golden prompt strategy guide showing models how to seamlessly split reasoning logic: Step 1 (Tool: write layout to disk) -> Step 2 (Tool: pass file path to build dashboard).
+
+## [0.2.0] - 2026-02-28
+
+### Added
+
+- **Database Connections**:
+  - `TWBEditor.set_mysql_connection`: Configure TWB to load data from a Local MySQL database.
+  - `TWBEditor.set_tableauserver_connection`: Configure TWB for a Tableau Server hosted datasource.
+  - Automatically clears template-included dashboards, worksheets, metadata, and column aliases during config to prevent phantom "ghost" fields.
+- **Dynamic Field Registration**:
+  - The `field_registry` will now automatically infer the field type natively via naming heuristics when initializing `configure_chart` on strictly offline unknown schemas.
+- **Declarative JSON Dashboard Layouts**:
+  - `add_dashboard` now accepts a deeply nested dictionary (JSON-friendly) `layout` schema, allowing complex, FlexBox-like hierarchical layouts.
+  - `add_dashboard` `layout` parameter also directly accepts a file path (string) to a `.json` file, easing the payload size for MCP LLM calls.
+  - Generates perfectly calculated XML `<zone>` absolute coordinates (in Tableau's 100,000 scale) for both relative weighting (`weight`) and exact sizes (`fixed_size`).
+  - Added `demo_declarative_layout.py` showcasing the JSON engine.
+- **MCP Server Tools**:
+  - Exposed `set_mysql_connection` and `set_tableauserver_connection` to the MCP Server.
+  - Upgraded `add_dashboard` MCP tool to accept JSON-based dictionaries and JSON file paths for the `layout` schema.
+- **Examples & Documentation**:
+  - Reorganized the `examples/` directory into `scripts/` (for Python demos) and `prompts/` (for natural language MCP prompts).
+  - Extracted test workflows into runnable demos (`demo_e2e_mcp_workflow.py` and `demo_connections.py`).
+
+## [0.1.0] - 2026-02-27
+
+### Added
+
+- **Core library** (`twilize`):
+  - `FieldRegistry`: Field name ↔ TWB internal reference mapping with expression parsing (SUM, AVG, COUNT, YEAR, etc.)
+  - `TWBEditor`: lxml-based TWB XML editor supporting:
+    - Template loading and field initialization
+    - Calculated field management (add/remove)
+    - Worksheet creation with configurable chart types (Bar, Line, Pie, Area, Circle, Text, Automatic)
+    - Color, size, label, detail, and wedge-size encodings
+    - Dashboard creation with layout-flow zone structure (vertical, horizontal, grid-2x2)
+    - Valid TWB output compatible with Tableau Desktop
+
+- **MCP Server** (`server.py`):
+  - 8 atomic tools: `create_workbook`, `list_fields`, `add_calculated_field`, `remove_calculated_field`, `add_worksheet`, `configure_chart`, `add_dashboard`, `save_workbook`
+  - FastMCP-based stdio transport
+
+- **Dashboard layouts**:
+  - Verified against Tableau Dashboard Layout Templates (c.2 (2) reference)
+  - Dashboard windows use `<viewpoints>` + `<active>` structure (not `<cards>`)
+  - Zone structure uses `layout-flow` with `param='vert'/'horz'`
+
+- **Tests**:
+  - `test_debug.py`: Step-by-step debug test generating intermediate TWB files
+  - `test_e2e.py`: End-to-end integration test covering all MCP tools
+  - `test_c2_replica.py`: Full replica of c.2 (2) dashboard layout with 8 worksheets
+
+- **Package configuration**:
+  - `pyproject.toml` with hatchling build backend
+  - `twilize` CLI entry point

twilize-0.13.0/CONTRIBUTING.md

@@ -0,0 +1,171 @@
+# Contributing to twilize
+
+## Quick start
+
+```bash
+git clone https://github.com/your-org/twilize
+cd twilize
+pip install -e ".[dev]"
+pytest
+```
+
+`[dev]` includes local contributor tooling (test/lint/type-check).  
+If you only need runtime usage, `pip install -e .` is enough.
+
+All tests should pass before you start. If any fail, check the known-issues
+section in `tests/README.md` first.
+
+---
+
+## Architecture overview
+
+```
+MCP tool call  (tools_workbook.py / tools_migration.py / tools_support.py)
+      │
+      ▼
+ChartsMixin method  (src/twilize/charts/__init__.py)
+      │  facade: stable public API, no logic
+      ▼
+Dispatcher function  (src/twilize/charts/dispatcher.py)
+      │  selects the right builder based on mark_type + routing_policy.py
+      ▼
+Concrete Builder  (builder_basic.py / builder_dual_axis.py / builder_pie.py / …)
+      │  constructs the lxml XML subtree for the worksheet
+      ▼
+TWBEditor XML tree  (twb_editor.py via lxml)
+      │
+      ▼
+save() → validate() → .twb / .twbx
+```
+
+**Rule:** Every new parameter must travel the full chain top to bottom.
+Adding it only to the builder but forgetting the MCP tool (or vice versa)
+causes silent divergence between the Python API and the MCP surface.
+
+---
+
+## Module responsibilities
+
+| Module | Role |
+|---|---|
+| `twb_editor.py` | Main editor class. Composed from mixins. Owns the lxml tree. |
+| `charts/__init__.py` | `ChartsMixin` — thin public facade, delegates to dispatcher |
+| `charts/dispatcher.py` | Selects builder, forwards all parameters |
+| `charts/routing_policy.py` | Rules for which builder handles which `mark_type` |
+| `charts/builder_base.py` | Shared XML helpers used by all builders |
+| `charts/builder_basic.py` | Bar, Line, Area, Scatter, Heatmap, and other standard marks |
+| `charts/builder_dual_axis.py` | Dual-axis compositions (two panes, synchronized axes) |
+| `charts/builder_pie.py` | Pie and donut (via extra_axes) |
+| `charts/builder_text.py` | Text / KPI cards with rich-text label support |
+| `charts/builder_maps.py` | Filled and symbol maps |
+| `charts/helpers.py` | `apply_worksheet_style`, `setup_table_style`, shared XML primitives |
+| `field_registry.py` | Tracks calculated fields added in this session; used for datasource-dep injection |
+| `capability_registry.py` | Declares what twilize supports; used by `analyze_twb` and `list_capabilities` |
+| `migration.py` | Field-mapping inference and workbook rewrite for datasource migration |
+| `validator.py` | Structural and XSD validation called by `save()` |
+| `mcp/` | MCP server tool definitions (thin wrappers; no logic lives here) |
+
+---
+
+## Adding a parameter to an existing chart
+
+Example: adding `my_param` to `configure_chart`.
+
+**Step 1 — Builder** (`builder_basic.py` or whichever builder handles the mark type)
+
+```python
+class BasicChartBuilder:
+    def __init__(self, ..., my_param: str | None = None):
+        self.my_param = my_param
+
+    def build(self):
+        ...
+        if self.my_param:
+            # write the relevant XML
+```
+
+**Step 2 — Dispatcher** (`charts/dispatcher.py`)
+
+```python
+def configure_chart(editor, ..., my_param: str | None = None) -> str:
+    ...
+    builder = BasicChartBuilder(..., my_param=my_param)
+```
+
+**Step 3 — ChartsMixin** (`charts/__init__.py`)
+
+```python
+def configure_chart(self, ..., my_param: str | None = None) -> str:
+    return dispatch_configure_chart(self, ..., my_param=my_param)
+```
+
+**Step 4 — MCP tool** (`mcp/tools_workbook.py`)
+
+```python
+@server.tool()
+def configure_chart(..., my_param: str | None = None) -> str:
+    return editor.configure_chart(..., my_param=my_param)
+```
+
+**Step 5 — Test**
+
+Add a test in `tests/` that calls `configure_chart` with the new parameter and
+asserts the expected XML is present using XPath.
+
+---
+
+## Adding a new chart type
+
+1. Create `src/twilize/charts/builder_mytype.py` subclassing `BaseChartBuilder`
+2. Add a routing rule in `charts/routing_policy.py`
+3. Import and dispatch in `charts/dispatcher.py`
+4. Declare the capability in `capability_registry.py`
+5. Wire through `ChartsMixin` and the MCP tool if needed
+6. Add at least one test and one example
+
+---
+
+## Adding a capability to the registry
+
+Open `src/twilize/capability_registry.py` and add an entry to `CAPABILITIES`:
+
+```python
+Capability(
+    kind="chart",
+    name="MyNewChart",
+    level="core",          # core | advanced | recipe | unsupported
+    description="...",
+    notes="",
+),
+```
+
+`level` controls what `list_capabilities` and `analyze_twb` report.
+
+---
+
+## Testing
+
+```bash
+# Full suite
+pytest
+
+# Single file
+pytest tests/test_chart_routing.py -v
+
+# Keep temp workbooks for inspection
+pytest --basetemp=output/pytest_tmp
+```
+
+Tests are integration tests: they build real `.twb` XML and assert structure
+with XPath. There are no mocks of the lxml tree. This is intentional — mocking
+the XML layer has historically hidden bugs that only appear in Tableau Desktop.
+
+---
+
+## Code style
+
+- Python 3.10+, no walrus operator in public API signatures
+- `from __future__ import annotations` at the top of every module
+- No logic in MCP tool functions — they are thin wrappers only
+- No silent `except Exception: pass` — log or re-raise with context
+- Imports at the top of files, not inside function bodies

twilize-0.13.0/Dockerfile

@@ -0,0 +1,32 @@
+# ---- Stage 1: Build the frontend ----
+FROM node:20-slim AS frontend-builder
+
+WORKDIR /app/extension/frontend
+COPY extension/frontend/package.json extension/frontend/package-lock.json* ./
+RUN npm install
+COPY extension/frontend/ ./
+RUN npm run build
+
+# ---- Stage 2: Python runtime ----
+FROM python:3.13-slim
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the full project
+COPY . .
+
+# Install the twilize package in editable mode
+RUN pip install --no-cache-dir -e .
+
+# Copy the built frontend from stage 1
+COPY --from=frontend-builder /app/extension/frontend/dist /app/extension/frontend/dist
+
+# Railway sets $PORT; default to 8000
+ENV PORT=8000
+EXPOSE ${PORT}
+
+CMD python -m uvicorn extension.backend.app:app --host 0.0.0.0 --port ${PORT}