v1.0.0: desktop GUI, MkDocs site, full CI + docs pipeline

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Lint
         run: uv run ruff check src tests
       - name: Type check
-        run: uv run mypy -p algo_discovery -p ads -p synth
+        run: uv run mypy -p algo_discovery -p ads -p synth -p gui
 
   python-test:
     name: Pytest (3.10, 3.12, 3.13)
@@ -98,3 +98,31 @@ jobs:
         run: uv sync --group dev
       - name: Run synth discover --smoke
         run: uv run python engine/runner.py discover
+
+  gui:
+    name: GUI core smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Sync deps
+        run: uv sync --group dev
+      - name: Headless GUI selftest
+        run: uv run python -m gui --selftest
+      - name: GUI core tests
+        run: uv run pytest -q tests/test_gui.py
+
+  docs:
+    name: Docs (strict build)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Sync docs deps
+        run: uv sync --group docs
+      - name: Build docs
+        run: uv run mkdocs build --strict --site-dir site

.github/workflows/pages.yml

@@ -18,8 +18,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Sync docs deps
+        run: uv sync --group docs
+      - name: Build docs site
+        run: uv run mkdocs build --strict --site-dir site
       - uses: actions/configure-pages@v5
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: docs
+          path: site
       - uses: actions/deploy-pages@v4

CONTRIBUTING.md

@@ -10,7 +10,7 @@ Requires Python >= 3.10 and [uv](https://docs.astral.sh/uv/), plus a JDK
 ```bash
 git clone https://github.com/dsk-dev-ai/algorithm-discovery-engine.git
 cd algorithm-discovery-engine
-uv sync --group dev
+uv sync --group dev --group docs
 ```
 
 ## Quality gates
@@ -23,7 +23,9 @@ python engine/runner.py build           # all four language tiers compile
 python engine/runner.py test            # catalog tests pass in all four languages
 python engine/runner.py discover        # synthesizer smoke pass (CI-friendly)
 uv run ruff check src tests
-uv run mypy -p algo_discovery -p ads -p synth
+uv run mypy -p algo_discovery -p ads -p synth -p gui
+uv run python -m gui --selftest
+uv run mkdocs build --strict
 ```
 
 ### Per-language quick checks

README.md

@@ -9,6 +9,8 @@
 [![Forks](https://img.shields.io/github/forks/dsk-dev-ai/algorithm-discovery-engine?style=flat-square&logo=github&logoColor=white)](https://github.com/dsk-dev-ai/algorithm-discovery-engine/forks)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Last commit](https://img.shields.io/github/last-commit/dsk-dev-ai/algorithm-discovery-engine?style=flat-square&logo=git&logoColor=white)]()
+[![Docs](https://img.shields.io/badge/docs-live-blue?style=flat-square&logo=materialformkdocs&logoColor=white)](https://dsk-dev-ai.github.io/algorithm-discovery-engine/)
+[![GUI](https://img.shields.io/badge/available-gui_tkinter-blueviolet?style=flat-square)](#desktop-gui)
 [![Sponsor](https://img.shields.io/badge/%E2%9D%A4%EF%B8%8F-Sponsor-red?style=flat-square&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/dsk-dev-ai)
 
 **Python** · **Java** · **C++** · **Rust**
@@ -38,10 +40,12 @@ game) from input/output examples alone — no APIs, no model calls.
   next-term predictions.
 - **Zero dependencies per language** — no framework, no package, no JIT magic; pure
   standard library in all four tiers.
+- **Desktop GUI** — a Tkinter app (`python -m gui`) built on the standard library only;
+  core logic is headless-tested in CI.
 - **Generated-then-committed test vectors** — identical tests enforced by CI in every
   language; a single `--check` keeps them in sync with the catalog.
 - **CI-green by default** — grid of Python 3.10–3.13, Java 21, GCC C++17, stable Rust,
-  plus a discovery-smoke job.
+  discovery-smoke, GUI-core smoke, and a strict docs build.
 
 ## Quick start
 
@@ -52,6 +56,7 @@ cd algorithm-discovery-engine
 python engine/runner.py test        # build + run the catalog suite in all 4 languages
 python engine/runner.py bench       # benchmark all tiers, side by side
 python engine/runner.py discover    # synthesize + verify algorithms from examples
+python -m gui                       # open the desktop app
 ```
 
 No install required — Python ≥ 3.10 and (for the non-Python tiers) a JDK, a C++17
@@ -154,13 +159,46 @@ explanation, and next-term prediction.
 uv run python -m algo_discovery 1 4 9 16
 ```
 
+## Desktop GUI
+
+A small **Tkinter** desktop app (no third-party runtime dependencies) wraps the
+three engines behind a clean dark-themed interface:
+
+```sh
+python -m gui                   # launch from the repo root
+python engine/runner.py gui     # same thing via the dispatcher
+ade-gui                         # if installed with pip/uv
+```
+
+| Tab               | What it does                                                           |
+| ----------------- | ---------------------------------------------------------------------- |
+| **Discover**      | Run the synthesizer (smoke/full), view the per-target verified table, open the report. |
+| **Pattern discovery** | Enter an integer sequence, discover ranked hypotheses with next-term predictions.    |
+| **Engine**        | Check vectors, run pytest, build all tiers, benchmark, open docs/GitHub links.       |
+
+Core logic lives in `gui/core.py` and is tested headlessly in CI (`-p gui` mypy
++ `pytest -q tests/test_gui.py`).
+
+## Documentation
+
+Full docs: **https://dsk-dev-ai.github.io/algorithm-discovery-engine/**
+
+Build locally:
+
+```sh
+uv sync --group docs
+uv run mkdocs serve          # live preview at http://127.0.0.1:8000
+```
+
 ## Development
 
 ```sh
-uv sync --group dev
-uv run pytest -q          # 118 tests (catalog + synthesizer)
+uv sync --group dev --group docs
+uv run pytest -q               # 118+ tests (catalog + synthesizer + GUI core)
 uv run ruff check src tests
-uv run mypy -p algo_discovery -p ads -p synth
+uv run mypy -p algo_discovery -p ads -p synth -p gui
+uv run python -m gui --selftest           # headless GUI smoke
+uv run mkdocs build --strict             # documentation builds cleanly
 python engine/runner.py check   # keep generated vectors in sync before committing
 ```
 
@@ -178,6 +216,8 @@ engine/runner.py                 build / test / benchmark / synthesize dispatche
 src/ads/                         Python solving engine (regular + advanced)
 src/algo_discovery/              pattern-discovery framework (original)
 src/synth/                       local algorithm synthesizer
+src/gui/                         Tkinter desktop app (stdlib only)
+docs/                            documentation site (MkDocs Material)
 languages/java/src/ads/          Java tier (+ TestRunner, Benchmark)
 languages/cpp/include/ads/       C++17 headers (+ tests, bench)
 languages/rust/src/              Rust tier (+ examples/benchmark.rs)

docs/contributing.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Thanks for your interest in contributing to the Algorithm Discovery Engine.
+
+## Setup
+
+Requires Python ≥ 3.10 and [uv](https://docs.astral.sh/uv/), plus a JDK
+(≥ 17), a C++17 compiler, and the Rust toolchain for the non-Python tiers.
+
+```bash
+git clone https://github.com/dsk-dev-ai/algorithm-discovery-engine.git
+cd algorithm-discovery-engine
+uv sync --group dev --group docs
+```
+
+## Quality gates
+
+Run the full check suite before submitting:
+
+```bash
+python engine/runner.py check          # generated vectors in sync w/ the catalog
+python engine/runner.py build           # all four language tiers compile
+python engine/runner.py test            # catalog tests pass in all four languages
+python engine/runner.py discover        # synthesizer smoke pass (CI-friendly)
+uv run ruff check src tests
+uv run mypy -p algo_discovery -p ads -p synth -p gui
+uv run pytest -q
+uv run python -m gui --selftest         # headless GUI core smoke test
+uv run mkdocs build --strict            # documentation builds cleanly
+```
+
+### Per-language quick checks
+
+```bash
+cd languages/java && javac -d out $(find src -name '*.java') && java -cp out ads.TestRunner
+cd languages/cpp && g++ -std=c++17 -O2 -I include tests/test_runner.cpp -o build/runner && ./build/runner
+cd languages/rust && cargo test --quiet
+```
+
+## Adding a catalog problem
+
+1. Add the problem to `catalog/problems.json` with empty `tests`.
+2. Implement it in every tier: `src/ads/`, `languages/java/`, `languages/cpp/`,
+   `languages/rust/` (following the existing per-problem conventions).
+3. Run `uv run pytest -q` to auto-generate and fill the test vectors, then run
+   `python engine/runner.py check` to confirm they are committed in sync.
+4. Wire it into `engine/runner.py` `BENCH_ALGOS` and each tier's benchmark if
+   you want it benchmarked.
+
+## Adding a discovery target
+
+1. Add a target entry to `catalog/discovery_targets.json` (id, kind, signature,
+   `arg_types`) with curated I/O examples.
+2. Provide an oracle + fuzz generator in `src/synth/corpus.py` (see
+   `oracle_jump_game` / `fuzz_reach` for a template).
+3. Verify with `uv run python -m synth discover --smoke` — the fully-verified
+   target should join the report as `verified`.
+
+## Documentation
+
+The site uses [MkDocs Material](https://squidfunk.github.io/mkdocs-material/):
+
+```bash
+uv run mkdocs serve    # local preview at http://127.0.0.1:8000
+uv run mkdocs build --strict   # CI gate — must stay warnings-free
+```
+
+Documentation lives in `docs/`; pages map to the nav in `mkdocs.yml`. The CI
+`docs` job builds with `--strict`, so dead links and broken fences block merges.
+
+## CI
+
+`.github/workflows/ci.yml` runs: ruff + mypy (all packages, including `gui`),
+pytest on Python 3.10/3.12/3.13, Java/C++/Rust tests, `gen_tests --check`, a
+discovery-smoke job, and a strict MkDocs build. `.github/workflows/pages.yml`
+deploys the docs to GitHub Pages on every push to `main`.
+
+## Releasing
+
+Version bumps bump `pyproject.toml`, add a GitHub tag matching the version, and
+a release with the changelog collated from the merged pull requests.

docs/engine.md

@@ -0,0 +1,71 @@
+# Multi-language engine
+
+## Catalog
+
+`catalog/problems.json` is the single source of truth. Every algorithm and
+structure carries a shared test-vector set that is checked in **all four
+languages**.
+
+| Algorithms (10)                                          | Data structures (6)            |
+| -------------------------------------------------------- | ------------------------------ |
+| `two_sum`, `binary_search`, `merge_sort`, `quick_sort`    | `stack`, `queue`, `linked_list` |
+| `max_subarray`, `lcs`, `knapsack_01`, `edit_distance`     | `bst`, `trie`, `min_heap`       |
+| `graph_bfs`, `graph_dfs`                                  |                                |
+
+`engine/gen_tests.py` expands these into identical per-language test vectors,
+which are committed so every tier runs the exact same dataset.
+
+## Language tiers
+
+| Tier   | Location                 | Approach                                       |
+| ------ | ------------------------ | ---------------------------------------------- |
+| Java   | `languages/java/`        | OO reference implementations                   |
+| C++    | `languages/cpp/`         | modern C++17, RAII, iterators                  |
+| Rust   | `languages/rust/`        | ownership-safe, zero dependencies              |
+| Python | `src/ads/`               | regular + advanced (`*_advanced`, mypy strict) |
+
+## Running the engine
+
+```sh
+python engine/runner.py check     # assert committed vectors match the catalog
+python engine/runner.py build     # compile every tier (no execution)
+python engine/runner.py test      # run the catalog suite in all 4 languages
+python engine/runner.py bench     # benchmark all tiers, print comparison table
+```
+
+## Sample benchmark
+
+Microseconds, lower is better:
+
+```
+algorithm             Python        Java         C++        Rust
+merge_sort           928,850      85,358      66,972      39,647
+quick_sort           702,918      41,562      22,942      17,610
+max_subarray         444,168      17,881       9,702          78
+two_sum               32,847      30,393     582,269     659,066
+lcs                  901,711      53,888      21,300      24,979
+knapsack_01            1,595      25,732      17,617      23,390
+```
+
+!!! note
+    Languages may pick different strategies for the same problem — Java's
+    `two_sum` uses a hash map while C++/Rust use a quadratic scan — so the table
+    showcases trade-offs rather than an exact contest.
+
+## Per-language checks
+
+```sh
+# Python
+uv run pytest -q
+uv run ruff check src tests
+uv run mypy -p algo_discovery -p ads -p synth -p gui
+
+# Java
+cd languages/java && javac -d out $(find src -name '*.java') && java -cp out ads.TestRunner
+
+# C++
+cd languages/cpp && g++ -std=c++17 -O2 -I include tests/test_runner.cpp -o build/runner && ./build/runner
+
+# Rust
+cd languages/rust && cargo test --quiet
+```

docs/gui.md

@@ -0,0 +1,61 @@
+# Desktop GUI
+
+A small **Tkinter** desktop app (pure standard library — no third-party
+dependencies) wraps the three engines behind buttons.
+
+## Launch
+
+```sh
+python -m gui              # from the repo root
+uv run python -m gui
+python engine/runner.py gui
+```
+
+`pip install algorithm-discovery-engine` won't include the GUI — the app is
+meant to run from a checkout — but nothing beyond Python ≥ 3.10 with `tkinter`
+is required.
+
+## Tabs
+
+### Discover
+
+Drives the [algorithm synthesizer](synthesis.md) from the UI.
+
+- **Run smoke pass** — CI-friendly reduced-budget pass (~2 min).
+- **Run full pass** — the full 600k-candidate budget.
+- **Refresh** — reload the latest `catalog/discoveries/report.json`.
+- **Open report (markdown)** / **Open solutions folder** — jump straight to the
+  generated report and `solutions/*.py`.
+
+The table shows per-target id, kind, status, novelty, search time, and strategy.
+Status colors mirror the CLI contract: green = verified, red = rejected.
+
+### Pattern discovery
+
+Type any integer sequence (spaces or commas, negatives welcome) and hit
+**Discover**. The ranked hypotheses render as a table with confidence, predicted
+next term, and the explanation from the [pattern discovery](patterns.md)
+framework.
+
+### Engine
+
+A scratch terminal for the multi-language engine:
+
+- **Check vectors** — assert committed vectors match the catalog.
+- **Run pytest** — the Python quality suite.
+- **Run build** — compile Java, C++17, and Rust tiers.
+- **Benchmark** — full cross-language benchmark table.
+- **Open docs / Open GitHub** — external links.
+
+Long-running actions run in a background thread with the buttons disabled; the
+status bar reports readiness and failures. The GUI is fully functional on a
+headless box only for the *core* logic (see `gui/core.py`); rendering needs a
+display.
+
+## Architecture
+
+```
+src/gui/core.py     pure logic (no tkinter) — tested headlessly in CI
+src/gui/app.py      Tkinter rendering + background worker thread
+src/gui/__main__.py launcher (python -m gui)
+```