<p>Codex Calc Engine helps Codex create, debug, translate, and optimize Tableau calculated fields. It combines field discovery, grain analysis, safe authoring, stored-formula read-back, and behavioral checks so a successful API response is not mistaken for a correct calculation.</p>
<h2>When to use it</h2>
<ul>
<li>Turn a business definition into a Tableau calculated field.</li>
<li>Repair mixed-aggregation, LOD, null, or table-calculation problems.</li>
<li>Translate supported SQL expressions into Tableau semantics.</li>
<li>Review an expensive calculation without changing its meaning.</li>
<li>Author a dependency-ordered batch of calculations.</li>
</ul>
<p>Use a workbook-authoring skill for dashboard layout, visual styling, or broad <code>.twb</code>/<code>.twbx</code> changes.</p>
<h2>Requirements</h2>
<ul>
<li>Codex with this skill installed or available.</li>
<li>A Tableau Desktop agent or MCP runtime for live discovery, authoring, and behavioral verification.</li>
<li>Python 3.10+ for the optional local formula checker.</li>
</ul>
<p>Without Tableau access, the skill can still draft formulas, but it will label storage and behavior as unverified.</p>
<h2>Installation</h2>
<p>Install the entire <code>codex-calc-engine</code> directory through your normal Codex skill or plugin workflow. Keep <code>SKILL.md</code>, <code>agents/</code>, and <code>skill-expertise/</code> together.</p>
<h2>Example prompts</h2>
<pre><code>Use $codex-calc-engine to create a 90-day retention rate using [User ID], [Order Date], and [First Order Date].
</code></pre>
<pre><code>Debug this Tableau calculation. It returns “cannot mix aggregate and non-aggregate”: SUM([Sales]) / [Customer Target].
</code></pre>
<pre><code>Translate this SQL window calculation into Tableau and explain the required table-calculation addressing.
</code></pre>
<h2>Local formula checks</h2>
<p>Normalize a candidate formula for comparison:</p>
<pre><code>python skill-expertise/calc_checks.py normalize --file formula.txt
</code></pre>
<p>Check a stored formula for common transport problems:</p>
<pre><code>python skill-expertise/calc_checks.py check --file stored-formula.txt --expect-operator &#39;&lt;&#39;
</code></pre>
<p>The checker is intentionally side-effect free. Tableau remains the authority for formula validity and workbook behavior.</p>
<h2>Verification model</h2>
<p>The skill distinguishes three outcomes:</p>
<ol>
<li><strong>Drafted</strong> — a formula was produced without live authoring.</li>
<li><strong>Stored</strong> — Tableau&#39;s stored definition was read back and matched.</li>
<li><strong>Behaviorally verified</strong> — representative workbook results were checked at the intended grain.</li>
</ol>
<p>Blocked checks remain blocked; the skill does not infer success from missing runtime access.</p>
<h2>Development</h2>
<p>Run the helper tests and active Codex skill validator before release:</p>
<pre><code>python -m unittest discover -s skill-expertise -v
</code></pre>


Codex Calc Engine helps Codex create, debug, translate, and optimize Tableau calculated fields. It combines field discovery, grain analysis, safe authoring, stored-formula read-back, and behavioral checks so a successful API response is not mistaken for a correct calculation.

## When to use it

* Turn a business definition into a Tableau calculated field.
* Repair mixed-aggregation, LOD, null, or table-calculation problems.
* Translate supported SQL expressions into Tableau semantics.
* Review an expensive calculation without changing its meaning.
* Author a dependency-ordered batch of calculations.

Use a workbook-authoring skill for dashboard layout, visual styling, or broad `.twb`/`.twbx` changes.

## Requirements

* Codex with this skill installed or available.
* A Tableau Desktop agent or MCP runtime for live discovery, authoring, and behavioral verification.
* Python 3.10+ for the optional local formula checker.

Without Tableau access, the skill can still draft formulas, but it will label storage and behavior as unverified.

## Installation

Install the entire `codex-calc-engine` directory through your normal Codex skill or plugin workflow. Keep `SKILL.md`, `agents/`, and `skill-expertise/` together.

## Example prompts

```text
Use $codex-calc-engine to create a 90-day retention rate using [User ID], [Order Date], and [First Order Date].
```

```text
Debug this Tableau calculation. It returns “cannot mix aggregate and non-aggregate”: SUM([Sales]) / [Customer Target].
```

```text
Translate this SQL window calculation into Tableau and explain the required table-calculation addressing.
```

## Local formula checks

Normalize a candidate formula for comparison:

```bash
python skill-expertise/calc_checks.py normalize --file formula.txt
```

Check a stored formula for common transport problems:

```bash
python skill-expertise/calc_checks.py check --file stored-formula.txt --expect-operator '<'
```

The checker is intentionally side-effect free. Tableau remains the authority for formula validity and workbook behavior.

## Verification model

The skill distinguishes three outcomes:

1. **Drafted** — a formula was produced without live authoring.
2. **Stored** — Tableau's stored definition was read back and matched.
3. **Behaviorally verified** — representative workbook results were checked at the intended grain.

Blocked checks remain blocked; the skill does not infer success from missing runtime access.

## Development

Run the helper tests and active Codex skill validator before release:

```bash
python -m unittest discover -s skill-expertise -v
```

Tableau Calc Engine (Codex)

Authors and verifies Tableau calculations with safe formula read-back.