From f6e8b36d25968264e5815849cfac12fa1bb19dbc Mon Sep 17 00:00:00 2001 From: Evan Gress <106449014+evangress@users.noreply.github.com> Date: Sat, 14 Nov 2026 09:37:33 -0500 Subject: [PATCH 1/2] Add a GitHub Pages site at docs/index.html One semantic HTML page styled by TagBrush.css from its CDN, with two TagBrush.css variables set (primary colour, reading width). It explains the tool, shows the unedited translation of corpus/ode_rk4.m, covers the pipeline, the honesty guarantee, install, commands, the LLM/MCP path and current coverage from `dualect rules list` and the corpus. docs/.nojekyll skips Jekyll processing. TagCheck --browser: 0 errors, 0 warnings. Co-Authored-By: Claude Fable 5.2 --- docs/.nojekyll | 0 docs/index.html | 377 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 377 insertions(+) create mode 100644 docs/.nojekyll create mode 100644 docs/index.html diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..3a3a82b --- /dev/null +++ b/docs/index.html @@ -0,0 +1,377 @@ + + + + + +dualect: verified translation between .m and Python/NumPy + + + + + + + + + + +Skip to content +
+ +
+

Translate numeric code between .m and NumPy, and check that it still computes the same thing

+

dualect is a command-line tool that translates scripts between .m files and Python/NumPy in both directions. It translates only what its tested rules cover, marks everything else as untranslated, and runs both versions to compare every variable.

+
+
+ Install and try it + Source on GitHub +
+
+
+ +
+
+

The problem

+

A lot of numerical code is written for Octave or MATLAB, and teams often want it in Python with NumPy, or need to move code the other way. The two languages look alike but differ in ways that change results without raising an error:

+
    +
  • Indexing starts at 1 and ranges include their end in .m code; NumPy starts at 0 and slices exclude their end.
  • +
  • * is a matrix product in .m code and an element-wise product in NumPy, where the matrix product is @.
  • +
  • linspace defaults to 100 points in .m code and 50 in NumPy.
  • +
  • .m arrays are copied on assignment; NumPy arrays can share memory through views.
  • +
+

Older translators are mostly unmaintained, go in one direction only, and produce Python that imitates the source language instead of plain NumPy. A general-purpose language model (LLM) often translates correctly, but nothing checks its output, and it re-derives the same rules on every request.

+

dualect takes a narrower approach. It keeps a rule for each construct or built-in function: a small folder that explains how the two languages differ and holds example pairs that are run in both. Rules that are reliable have a deterministic translator. The rest are handed to an LLM as focused context. Whichever way a translation is produced, dualect runs the source and the result and compares their outputs.

+
+ +
+

An example

+

This is corpus/ode_rk4.m from the repository, a fourth-order Runge-Kutta integration of a damped oscillator, followed by the Python file dualect writes for it with dualect translate corpus/ode_rk4.m -o ode_rk4.py. Neither listing has been edited.

+
+
Input: ode_rk4.m
+
% Damped harmonic oscillator x'' + 2 zeta w0 x' + w0^2 x = 0, integrated with
+% the classic fourth-order Runge-Kutta method and compared with the exact
+% solution.
+w0 = 2*pi;          % natural frequency [rad/s]
+zeta = 0.1;         % damping ratio
+f = @(t, y) [y(2); -2*zeta*w0*y(2) - w0^2*y(1)];
+
+t_end = 3;
+h = 0.01;
+t = 0:h:t_end;
+n = numel(t);
+y = zeros(2, n);
+y(:, 1) = [1; 0];   % x(0) = 1, x'(0) = 0
+
+for k = 1:n-1
+  k1 = f(t(k), y(:, k));
+  k2 = f(t(k) + h/2, y(:, k) + h/2*k1);
+  k3 = f(t(k) + h/2, y(:, k) + h/2*k2);
+  k4 = f(t(k) + h, y(:, k) + h*k3);
+  y(:, k+1) = y(:, k) + h/6*(k1 + 2*k2 + 2*k3 + k4);
+end
+
+wd = w0*sqrt(1 - zeta^2);
+x_exact = exp(-zeta*w0*t) .* (cos(wd*t) + zeta*w0/wd*sin(wd*t));
+err = max(abs(y(1, :) - x_exact));
+energy = 0.5*y(2, :).^2 + 0.5*w0^2*y(1, :).^2;
+decay = energy(end) / energy(1);
+
+
+
Output: ode_rk4.py, as written by dualect
+
# Translated from ode_rk4.m by dualect; verified against the .m source.
+import numpy as np
+
+# Damped harmonic oscillator x'' + 2 zeta w0 x' + w0^2 x = 0, integrated with
+# the classic fourth-order Runge-Kutta method and compared with the exact
+# solution.
+w0 = 2 * np.pi  # natural frequency [rad/s]
+zeta = 0.1  # damping ratio
+f = lambda t, y, zeta=zeta, w0=w0: np.array(
+    [y[1], -2 * zeta * w0 * y[1] - w0**2 * y[0]]
+)
+
+t_end = 3
+h = 0.01
+t = np.linspace(0, t_end, 301)
+n = t.size
+y = np.zeros((2, n))
+y[:, 0] = np.array([1, 0])  # x(0) = 1, x'(0) = 0
+
+# dualect: index k
+for k in range(n - 1):
+    k1 = f(t[k], y[:, k])
+    k2 = f(t[k] + h / 2, y[:, k] + h / 2 * k1)
+    k3 = f(t[k] + h / 2, y[:, k] + h / 2 * k2)
+    k4 = f(t[k] + h, y[:, k] + h * k3)
+    y[:, k + 1] = y[:, k] + h / 6 * (k1 + 2 * k2 + 2 * k3 + k4)
+
+wd = w0 * np.sqrt(1 - zeta**2)  # dualect: assumed sqrt argument in the real domain
+x_exact = np.exp(-zeta * w0 * t) * (np.cos(wd * t) + zeta * w0 / wd * np.sin(wd * t))
+err = np.nanmax(np.abs(y[0, :] - x_exact))
+energy = 0.5 * y[1, :] ** 2 + 0.5 * w0**2 * y[0, :] ** 2
+decay = energy[-1] / energy[0]
+
+

Points worth noticing:

+
    +
  • The first line records the verdict. dualect ran both files, and all 18 variables the .m script leaves behind matched within the default tolerance (the function handle f is only checked for being callable on both sides).
  • +
  • 0:h:t_end became np.linspace(0, t_end, 301), because np.arange with a fractional step can gain or lose the end point to rounding.
  • +
  • Loop indices shifted to 0-based. # dualect: index k tells the checker that k holds a position, so it compares it as one less than the .m value.
  • +
  • max became np.nanmax, because the .m function ignores NaN values and np.max does not.
  • +
  • Where dualect had to assume something it could not prove, such as sqrt of a non-negative number, it says so in a # dualect: assumed … comment.
  • +
+
+ +
+

How it works

+ +

Rules

+

Each rule is one folder, rules/<category>/<rule-id>/, with three parts:

+
+
rule.yaml
+
The construct in each language, why they differ and the known pitfalls, written to be read by a person learning the difference and by an LLM applying it.
+
translate.py
+
An optional deterministic translator for the construct, in one or both directions.
+
cases/
+
Pairs of .m and .py files that are run in both languages and compared in the test suite.
+
+

Keeping rules small and independent means that when a language changes, one folder changes and only its tests fail. A behavior that changed between language versions gets a new rule with its own version range rather than an edit to the old one.

+ +

Status

+

Every rule has a status for each direction of translation:

+
+
unsupported
+
The construct is documented so that it can be reported by name, but nothing translates it.
+
guided
+
No translator yet. The rule text and its cases are given to an LLM, and the LLM's output is verified like any other.
+
mechanical
+
The rule's translate.py translates it, and every case translates and verifies. The test suite fails if a mechanical rule stops qualifying, or if a guided rule qualifies and has not been promoted.
+
+ +

Pipeline

+
    +
  1. Parse. .m files are parsed with tree-sitter; Python files with the standard ast module. Both are lowered into one small intermediate representation, so the same rules serve both directions.
  2. +
  3. Scan. Each node is tagged with the rules it needs. Anything with no rule is recorded as unsupported, with its line and column.
  4. +
  5. Translate. Each statement is translated by the translators of its rules. A statement that cannot be translated with confidence is left as a marked hole.
  6. +
  7. Emit. The output is assembled; Python output is formatted with ruff.
  8. +
  9. Verify. Both files are run and their results compared, unless verification is turned off.
  10. +
+ +

Verification by execution

+

The .m side runs in GNU Octave through oct2py, in a cleared workspace; the Python side runs in a fresh namespace. Each variable the .m script leaves in its workspace must exist in Python with an equal value, compared with numpy.allclose (default rtol=1e-9, atol=1e-12, adjustable per rule) and with NaN equal to NaN. A 1×N row equals a 1-D NumPy array, but other shape differences fail, and so does logical against numeric. Index variables marked with a dualect: index comment are compared as 1-based against 0-based.

+

Verification shows that the two programs agree on the values the script computes when it runs as written. It does not prove that they agree on every possible input.

+
+ +
+

What it will not do

+

dualect does not guess. Its rule is that a wrong translation that looks right is worse than no translation.

+
    +
  • A statement that needs a construct with no rule, or a translator that declines because the shape or type of a value is not known, is not translated. In Python output it becomes a TODO(dualect) comment followed by raise NotImplementedError(...); in .m output, a % TODO(dualect) comment followed by error(...). The report lists each one with its line and the reason.
  • +
  • An output that was not verified says so on its first line, for example # Translated from beam_deflection.m by dualect. UNVERIFIED: 1 statement(s) not translated.
  • +
  • --strict writes nothing at all if any statement would be left untranslated.
  • +
  • Python behavior with no .m counterpart is declined rather than imitated: writing through a NumPy view, a function that modifies its array argument, a lambda that reads a variable changed later, and max or argmax over data that may hold NaN.
  • +
  • Output is plain NumPy. There is no helper module that emulates the other language; a construct with no clean NumPy form stays guided or unsupported.
  • +
+

dualect itself never calls an LLM. When an LLM fills a hole, its code is checked with dualect verify like everything else.

+
+ +
+

Install and quick start

+

dualect needs Python 3.11 or later, uv, and GNU Octave for anything that runs .m code (translate with verification, verify, and the execution tests). It is not published on PyPI yet; run it from a clone.

+
+
brew install octave            # macOS; on Debian or Ubuntu: sudo apt install octave
+git clone https://github.com/kovirlabs/dualect.git
+cd dualect
+uv sync --all-groups
+uv run dualect --version
+
Installing from source.
+
+ +

From .m to Python

+
+
uv run dualect scan corpus/ode_rk4.m                    # which rules does it need?
+uv run dualect translate corpus/ode_rk4.m -o ode_rk4.py # translate, then run both and compare
+
The direction follows the file suffix of the input.
+
+

The last lines of the report for this file are:

+
+
23 statements: 23 mechanical, 0 guided, 0 unsupported
+verify corpus/ode_rk4.m <-> ode_rk4.py
+  ok   decay
+  …
+PASS
+verified: yes
+wrote ode_rk4.py
+
Abridged; the full report also lists every statement and every compared variable.
+
+

The .m side may use Octave syntax such as # comments, !=, +=, do … until and endfunction. With --dialect matlab, those are reported as Octave-only.

+ +

From Python to .m

+

Given this trapezoid.py:

+
+
import numpy as np
+
+x = np.linspace(0, np.pi, 101)
+y = np.sin(x)
+area = 0.0
+for k in range(x.size - 1):
+    area = area + (x[k + 1] - x[k]) * (y[k] + y[k + 1]) / 2
+err = abs(area - 2)
+
Input: trapezoid.py
+
+

uv run dualect translate trapezoid.py -o trapezoid.m writes:

+
+
% Translated from trapezoid.py by dualect; verified against the .py source.
+x = linspace(0, pi, 101);
+y = sin(x);
+area = 0.0;
+for k = 0:numel(x) - 2
+  area = area + (x(k + 2) - x(k + 1)) * (y(k + 1) + y(k + 2)) / 2;
+end
+err = abs(area - 2);
+
Output: trapezoid.m. Variables keep their Python values, so k still counts from 0 and the indices add 1.
+
+ +

Reading the report

+

For each statement, translate prints its line and column, its kind, the status used, whether it was verified, and the rules it used. Below a statement that was not translated, it prints why (for example needs call:filter (no rule)). The summary line counts statements by status, and the verified: line gives the verdict.

+ + + + + + + + + + +
Exit codes of dualect translate
CodeMeaning
0Every statement was translated and the output verified.
1Verification ran and found a difference, or --strict refused to write an incomplete translation.
4The output was written but is not verified: it has untranslated statements, or --no-verify was given.
+

dualect verify exits with 0 when every variable matches and 1 otherwise. dualect rules check exits with 1 when a rule's status is not earned.

+
+ +
+

Commands

+ + + + + + + + + + + + + + + + +
The dualect command line
CommandWhat it does
translate FILE -o OUTTranslates a .m file to Python or a .py file to .m, then verifies. Options: --strict, --no-verify, --dialect (for example octave or matlab@R2023a).
scan FILELists the rules a file needs, where each is used, and the constructs that have no rule. --json gives machine-readable output.
context FILEPrints the rules the file needs, with their cases, as Markdown for an LLM prompt.
verify M_FILE PY_FILERuns both scripts and compares every variable. Options: --rtol, --atol, --index NAME, --ignore NAME.
rules listLists every rule with its status in each direction and its number of cases. Filters: --status, --direction.
rules check [RULE_ID …]Runs each rule's translator on its cases in each direction and fails when a status is not earned.
rules new CATEGORY/NAMECreates a rule folder with a rule.yaml and one case pair to fill in.
llms-txt -o llms.txtRegenerates the one-line-per-rule index.
mcpServes scan, get_rule, translate and verify as tools over the Model Context Protocol, on standard input and output.
+
+ +
+

Working with an LLM

+

The guided path is how statements without a deterministic translation get done. dualect supplies the knowledge and the check; the LLM you already use writes the code.

+
    +
  1. dualect translate leaves the statements it could not translate as marked holes.
  2. +
  3. dualect context FILE prints only the rules that file needs: each rule's rule.yaml and one or two verified case pairs, ready to paste into a prompt.
  4. +
  5. The LLM fills the holes.
  6. +
  7. dualect verify runs both files and compares every variable.
  8. +
+

llms.txt lists every rule in one line, with its status per direction and its number of cases, so a model can find the rule it needs without reading the whole repository.

+

An LLM client that supports the Model Context Protocol (MCP), such as Claude Code or Claude Desktop, can call the same functions as tools. A client configuration looks like this:

+
+
{"mcpServers": {"dualect": {"command": "uv",
+  "args": ["run", "--directory", "/path/to/dualect", "dualect", "mcp"]}}}
+
MCP client configuration; replace /path/to/dualect with your clone.
+
+
+ +
+

Current coverage

+

dualect is at version 0.1.0 and early. These numbers come from dualect rules list and the test suite.

+
+
Rules
+
35, with 49 case pairs between them.
+
.m to Python
+
30 mechanical, 5 guided.
+
Python to .m
+
29 mechanical, 3 guided; 3 rules cover constructs that exist only in .m code.
+
+ +

Rules not yet mechanical

+ + + + + + + + + + + + +
Rules that are guided in at least one direction
Rule.m to PythonPython to .mWhat is missing
functions/multiple-returnsguidedmechanicalBodies that depend on nargout need to collapse into one tuple return.
functions/narginguidedguidedDefault-argument patterns need facts about arguments that the analysis does not derive.
indexing/grow-on-assignguidedguidedGrowing an array past its end needs rewrites that span several statements.
io/displayguidedguidedprintf-style formats and displaying values without a semicolon.
syntax/command-syntaxguidednot applicableIts case needs strsplit, which has no rule.
+

The other 30 rules are mechanical in every direction they apply to. They cover comments and line continuation, array literals, character strings, one-based and logical indexing, end in an index, colon ranges, A(:), arithmetic, division and linear solves, matrix and element-wise products and powers, transposes, comparisons, logical NOT and short-circuit logic, augmented assignment, for, while, if and switch, function definitions, constants, element-wise math, zeros/ones/eye, linspace, size/numel/length, sum/mean/max/min, find and isempty. The full list is in llms.txt.

+ +

Example scripts

+

The repository's corpus/ holds three realistic scripts that combine many constructs, translated from .m to Python in the test suite.

+ + + + + + + + + + +
Results for the example scripts, .m to Python
ScriptStatementsTranslatedNot translatedVerified
ode_rk4.m23230Yes
beam_deflection.m30291: fprintf is guidedNo
signal_filter.m33294: filter has no rule, and two max calls depend on its resultNo
+

In the other direction, the Python that dualect writes for ode_rk4.m translates back to .m completely and verifies against that Python.

+ +

Not supported yet

+

Any construct without a rule is reported as unsupported. Today that includes cell arrays, structs, plotting, random numbers, file input and output, and most built-in functions beyond the list above, including filter. Classes (classdef), GUIs, Simulink, MEX files and toolboxes are out of scope for now.

+
+ + +
+
+ + + From 325f7aa2363b5123dfa4492b9710a03116cfa5b9 Mon Sep 17 00:00:00 2001 From: Evan Gress <106449014+evangress@users.noreply.github.com> Date: Sat, 14 Nov 2026 09:39:25 -0500 Subject: [PATCH 2/2] Rewrite README for a first-time reader A one-paragraph statement, a real excerpt of the ode_rk4 translation, install, quick start in both directions, how to read the report and the exit codes, the commands, how rules work and how to add one, the LLM/MCP path, status and limits with numbers from `dualect rules list` and the corpus, and development commands. CLAUDE.md now points at docs/index.html. Co-Authored-By: Claude Fable 5.2 --- CLAUDE.md | 2 + README.md | 261 +++++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 203 insertions(+), 60 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a19bcab..7aebfcc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,6 +24,8 @@ status is earned; `dualect mcp` serves scan/get_rule/translate/verify; Adversarial probes live in tests/test_adversarial.py and tests/test_reverse.py. Next: more rules (the guided ones, `cumsum`, `filter`, printing), cell arrays and structs. +The project site is `docs/index.html` (GitHub Pages from `/docs`, TagBrush.css); +keep its numbers in step with README.md and run TagCheck after editing it. ## Core ideas to preserve diff --git a/README.md b/README.md index a8449b9..821bf54 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,241 @@ # dualect -Translate numeric code between Octave/MATLAB-style `.m` files and Python/NumPy, -in both directions, with every translation **verified by running both sides**. +dualect translates numeric code between `.m` files (Octave/MATLAB style) and +Python/NumPy, in both directions, and checks every translation by running both +sides and comparing the results. It is a tested knowledge base of translation +*rules*, one small folder per language construct or built-in function, plus a +deterministic engine that applies the reliable ones. Statements it cannot +translate with confidence are left as marked holes and reported, never guessed; +an LLM can fill them using the same rules as context, and its output is checked +the same way. + +Site: https://kovirlabs.github.io/dualect/ · Design: [docs/design.md](docs/design.md) + +> **Status: early (0.1.0).** 35 rules. `.m` → Python: 30 mechanical, 5 guided. +> Python → `.m`: 29 mechanical, 3 guided. Details under [Status and limits](#status-and-limits). + +## Example + +[`corpus/ode_rk4.m`](corpus/ode_rk4.m) integrates a damped oscillator with +Runge-Kutta. An excerpt of the input: + +```matlab +t = 0:h:t_end; +n = numel(t); +y = zeros(2, n); +y(:, 1) = [1; 0]; % x(0) = 1, x'(0) = 0 + +for k = 1:n-1 + k1 = f(t(k), y(:, k)); + ... +err = max(abs(y(1, :) - x_exact)); +``` + +and the corresponding part of what `dualect translate corpus/ode_rk4.m -o ode_rk4.py` +writes: -> **Status: early.** Both directions work end to end: `.m` → Python with 30 of 35 -> rules mechanical, Python → `.m` with 29 mechanical, every case verified by running -> both languages. See [docs/design.md](docs/design.md) section 11. +```python +# Translated from ode_rk4.m by dualect; verified against the .m source. +import numpy as np -## Why +... +t = np.linspace(0, t_end, 301) +n = t.size +y = np.zeros((2, n)) +y[:, 0] = np.array([1, 0]) # x(0) = 1, x'(0) = 0 -Existing translators are mostly abandoned, go one way only, and produce Python that -imitates MATLAB instead of idiomatic NumPy. LLMs can translate, but they re-derive -the same tricky rules every time and nothing checks the result. +# dualect: index k +for k in range(n - 1): + k1 = f(t[k], y[:, k]) + ... +err = np.nanmax(np.abs(y[0, :] - x_exact)) +``` -dualect is built around **rules**: one small, tested folder per language construct -or built-in (indexing with `end`, `*` vs `.*`, `linspace`, ...). Dependable rules get -a scripted translator; the rest are handed to an LLM as focused context; every -result is executed and compared. +The first line is the verdict: both files were run and all 18 variables matched. +`max` became `np.nanmax` because the `.m` `max` skips NaN; `# dualect: index k` +tells the checker that `k` holds a position and is 0-based on the Python side. -## Usage +## Install + +dualect needs Python 3.11+, [uv](https://docs.astral.sh/uv/), and GNU Octave for +anything that runs `.m` code (`translate` with verification, `verify`, and the +execution tests). It is not on PyPI yet. ```bash -uv sync --all-groups # install (Python 3.11+, uv) -uv run pytest # rules, translators, corpus, both directions -uv run ruff check . && uv run ruff format --check . -uv run mypy dualect && uv run python tools/mypy_rules.py +brew install octave # or: sudo apt install octave +git clone https://github.com/kovirlabs/dualect.git && cd dualect +uv sync --all-groups +uv run dualect --version ``` -### `.m` → Python +## Quick start + +The direction follows the input file's suffix. + +**`.m` → Python** ```bash -uv run dualect translate script.m -o script.py # translate, then verify by running both -uv run dualect scan script.m # which rules does it need? what has none? -uv run dualect context script.m # those rules as LLM-ready prompt context -uv run dualect verify script.m script.py # run both sides, compare every variable +uv run dualect scan corpus/ode_rk4.m # rules it needs; constructs with none +uv run dualect translate corpus/ode_rk4.m -o ode_rk4.py # translate, then run both and compare ``` -`translate` handles each statement with the rules' deterministic translators. A -statement it cannot translate correctly is left as a `TODO(dualect)` hole that raises -`NotImplementedError`, and is reported; `dualect context` prints the rules an LLM -needs to fill it, and `--strict` refuses to write anything incomplete. The first line -of the output says whether it was verified against the `.m` source. Where a shape had -to be assumed the line says so (`# dualect: assumed ...`), and `# dualect: index k` -marks a variable stored 0-based because it only ever holds positions. +**Python → `.m`.** Given `trapezoid.py`: + +```python +import numpy as np + +x = np.linspace(0, np.pi, 101) +y = np.sin(x) +area = 0.0 +for k in range(x.size - 1): + area = area + (x[k + 1] - x[k]) * (y[k] + y[k + 1]) / 2 +err = abs(area - 2) +``` + +`uv run dualect translate trapezoid.py -o trapezoid.m` writes: + +```matlab +% Translated from trapezoid.py by dualect; verified against the .py source. +x = linspace(0, pi, 101); +y = sin(x); +area = 0.0; +for k = 0:numel(x) - 2 + area = area + (x(k + 2) - x(k + 1)) * (y(k + 1) + y(k + 2)) / 2; +end +err = abs(area - 2); +``` + +Variables keep their Python values (`k` still counts from 0), so indices add 1. +Python behaviour with no `.m` counterpart is declined rather than imitated: +writing through a NumPy view, a function that modifies its array argument, a +lambda that reads a variable changed later, `max`/`argmax` over data that may +hold NaN, and similar ([design section 5.5](docs/design.md)). The `.m` side may use Octave syntax (`#` comments, `!=`, `++`, `+=`, `do ... until`, `endfunction`); `--dialect matlab` reports it as Octave-only. -### Python → `.m` +## Reading the report -```bash -uv run dualect translate model.py -o model.m # the direction follows the suffix -uv run dualect scan model.py # rules needed, Python constructs with none -uv run dualect context model.py -``` +`translate` prints one line per statement: line and column, kind, the status +used, whether it was verified, and the rules it used. Under a statement it could +not translate, it prints why, for example `needs call:filter (no rule)` or +`translator declined: max of a value whose shape is unknown or along a singleton dimension`. Then come a +summary (`30 statements: 29 mechanical, 1 guided, 0 unsupported`), the +per-variable comparison when verification ran, and a `verified:` line. + +An untranslated statement becomes a hole in the output: in Python, a +`# TODO(dualect)` comment quoting the source line followed by +`raise NotImplementedError(...)`; in `.m`, a `% TODO(dualect)` comment followed +by `error(...)`. The output's first line then says `UNVERIFIED` and why. +`# dualect: assumed ...` marks an assumption the engine could not prove (for +example a real `sqrt` argument). -The same rules translate back: a 1-D NumPy array becomes a `1xN` row, `A @ v` -becomes `(A * v.').'`, `x[i]` becomes `x(i + 1)` (variables keep their Python -values), and the output is checked by running the `.py` and the `.m`. Holes are -`% TODO(dualect)` comments followed by `error(...)`. Python behaviour with no `.m` -counterpart is declined, not imitated: writing through a NumPy view or alias, a -function writing into its array argument, a lambda that reads a variable changed -later, `max` of data that may hold NaN, and the like (design section 5.5). +| Exit code | `translate` | `verify` | +|---|---|---| +| 0 | complete and verified | every variable matches | +| 1 | verification found a difference, or `--strict` refused to write | a variable differs or is missing | +| 4 | written but unverified: holes remain, or `--no-verify` was given | — | -### Rules +`--strict` writes nothing if any statement would be left as a hole. + +## Commands ```bash +uv run dualect translate FILE -o OUT [--strict] [--no-verify] [--dialect octave|matlab@R2023a] +uv run dualect scan FILE [--json] # rules a file needs, and constructs with none +uv run dualect context FILE # those rules and their cases, as LLM prompt context +uv run dualect verify FILE.m FILE.py # run both, compare every variable + # [--rtol] [--atol] [--index NAME] [--ignore NAME] uv run dualect rules list [--status guided] [--direction from-python] -uv run dualect rules check [RULE_ID ...] # does each rule earn its status, both ways? -uv run dualect rules new indexing/foo # scaffold a rule folder -uv run dualect llms-txt -o llms.txt # regenerate the one-line-per-rule index +uv run dualect rules check [RULE_ID ...] # does each rule earn its status, both ways? +uv run dualect rules new CATEGORY/NAME # scaffold a rule folder +uv run dualect llms-txt -o llms.txt # regenerate the one-line-per-rule index +uv run dualect mcp # MCP server on stdio ``` -`rules check` runs every rule's translator on its cases in each direction, compares -the result with the hand-written target and runs both sides; it fails when a rule -marked `mechanical` does not qualify, or a `guided` one does (promote it). -[`llms.txt`](llms.txt) lists every rule in one line for an LLM. +## Rules -### MCP server +Each rule is a folder `rules///`: -```bash -uv run dualect mcp # stdio; tools: scan, get_rule, translate, verify -``` +- `rule.yaml`: the construct in each language, `why` they differ and the + `pitfalls`, written for a person learning the difference and for an LLM + applying it; the construct tags it `match`es; its status per direction. +- `translate.py` (optional): the deterministic translator, for one or both directions. +- `cases/*.m` + `*.py`: paired examples, run in both languages and compared. + +A rule's status, per direction, is `unsupported` (documented so it can be +reported by name), `guided` (an LLM applies it; the result is verified) or +`mechanical` (its `translate.py` translates every case, and each verifies). +`rules check` fails when a `mechanical` rule no longer qualifies, or when a +`guided` one qualifies and should be promoted. A behaviour that changed between +language versions gets a new rule with `since`/`until`, not an edit to the old one. + +To add a rule: + +1. `uv run dualect rules new indexing/my-rule`, then fill in `rule.yaml` and + `cases/basic.m` + `cases/basic.py`, removing every `TODO`. +2. `uv run pytest tests/test_rules.py` runs the cases in both languages. +3. Optionally write `translate.py` (see existing rules such as + [`rules/builtins/linspace`](rules/builtins/linspace)) and set the status to + `mechanical` once `uv run dualect rules check indexing/my-rule` passes. +4. `uv run dualect llms-txt -o llms.txt` (a test fails when it is stale). + +The rule format and the pipeline are specified in [docs/design.md](docs/design.md) +sections 4 and 5. -A client configuration (Claude Code, Claude Desktop, ...) looks like: +## Using it with an LLM + +dualect never calls an LLM API itself; it supplies the knowledge and the check. +`dualect context FILE` prints only the rules that file needs, with verified case +pairs; the LLM fills the holes; `dualect verify` checks the result. +[`llms.txt`](llms.txt) lists every rule in one line. + +`dualect mcp` serves the tools `scan`, `get_rule`, `translate` and `verify` over +the Model Context Protocol (stdio). A client configuration (Claude Code, Claude +Desktop, ...) looks like: ```json {"mcpServers": {"dualect": {"command": "uv", "args": ["run", "--directory", "/path/to/dualect", "dualect", "mcp"]}}} ``` -The server gives the client's model the rules and the checks; dualect itself never -calls an LLM API, and anything the model writes can be checked with `verify`. +## Status and limits + +From `uv run dualect rules list`: 35 rules with 49 case pairs. + +- `.m` → Python: 30 mechanical; guided: `functions/multiple-returns`, + `functions/nargin`, `indexing/grow-on-assign`, `io/display`, + `syntax/command-syntax`. +- Python → `.m`: 29 mechanical; guided: `functions/nargin`, + `indexing/grow-on-assign`, `io/display`; 3 rules cover `.m`-only constructs. + +The [`corpus/`](corpus) scripts, `.m` → Python: + +| Script | Statements | Translated | Verified | +|---|---|---|---| +| `ode_rk4.m` | 23 | 23 | yes | +| `beam_deflection.m` | 30 | 29 (`fprintf` is guided) | no | +| `signal_filter.m` | 33 | 29 (`filter` has no rule; two `max` calls depend on it) | no | + +The Python that dualect writes for `ode_rk4.m` translates back to `.m` and verifies. + +Not supported yet: cell arrays, structs, plotting, random numbers, file I/O and +most built-ins beyond the rules listed in `llms.txt`. Out of scope for now: +`classdef`, GUIs, Simulink, MEX and toolboxes. Verification shows the two +programs agree when run as written, not on every possible input. + +## Development + +```bash +uv sync --all-groups +uv run pytest # Octave tests skip if Octave is absent +uv run ruff check . && uv run ruff format --check . +uv run mypy dualect && uv run python tools/mypy_rules.py +``` -`translate`, `verify` and the execution tests need GNU Octave (`brew install octave`, -`apt install octave`). +CI installs Octave and sets `DUALECT_REQUIRE_OCTAVE=1`, so Octave tests fail +there instead of skipping. The project site is the single page +[`docs/index.html`](docs/index.html), served by GitHub Pages from `/docs`. ## License