Initialize Continuator Web Pilot

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.gitignore
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.DS_Store
+.venv
+venv
+node_modules
+backend/data/*.sqlite3
+backend/data/*.sqlite3-*
+

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.DS_Store
+.venv/
+venv/
+node_modules/
+backend/data/*.sqlite3
+backend/data/*.sqlite3-*
+

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+RUN useradd -m -u 1000 user
+USER user
+WORKDIR $HOME/app
+
+COPY --chown=user backend/requirements.txt backend/requirements.txt
+RUN pip install --upgrade pip && pip install -r backend/requirements.txt
+
+COPY --chown=user backend backend
+COPY --chown=user frontend frontend
+
+EXPOSE 7860
+
+CMD ["python", "-m", "uvicorn", "app.main:app", "--app-dir", "backend", "--host", "0.0.0.0", "--port", "7860"]
+

README.md

@@ -0,0 +1,392 @@
+---
+title: Continuator Web Pilot
+emoji: 🎹
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Continuator Web Pilot
+
+This repository is a browser-based front-end and API wrapper for the Continuator system.
+It lets a user play a MIDI phrase in the browser, send that phrase to a Python Continuator engine, receive a generated continuation, and play it back immediately.
+
+The current implementation is meant as an MVP for experimentation, demos, and architecture validation. It already supports:
+
+- Browser-side real-time MIDI capture with the Web MIDI API.
+- A `FastAPI` backend that wraps the Python Continuator engine.
+- One isolated Continuator engine per live session.
+- SQLite logging for captured and generated phrases.
+- A compact UI with MIDI controls, phrase playback, and session activity views.
+- A tabbed `History | Memory` activity card.
+- Docker packaging suitable for local containers and Hugging Face Docker Spaces.
+
+## Goals
+
+This project is trying to validate a web architecture for Continuator with a clear separation of responsibilities:
+
+- The browser owns the real-time MIDI interaction.
+- The Python backend owns phrase learning and generation.
+- Session state is isolated so multiple users do not share musical memory by accident.
+- Phrase history is stored separately from the live model state.
+
+This is important because the original Continuator codebase is centered on local Python usage, while this project explores a true client-server version with a JavaScript front-end.
+
+## Current Scope
+
+What is implemented today:
+
+- Session creation and reset.
+- Web MIDI input selection in the browser.
+- Browser synth playback or hardware MIDI output playback.
+- Phrase capture based on silence detection.
+- Continuator settings exposed through a compact advanced drawer.
+- Per-session `History` and `Memory` visualization.
+
+What is intentionally not implemented yet:
+
+- Persistent user accounts.
+- Persistent per-user musical memory across sessions.
+- Shared session storage across multiple backend instances.
+- A production-grade multi-user database architecture.
+
+## Product And UX Overview
+
+The UI is organized around a simple performance loop:
+
+- `Session`: create a new isolated Continuator session or reset its memory.
+- `MIDI I/O`: connect browser MIDI, choose an input port, and choose a playback output.
+- `Phrase Flow`: monitor captured and generated note counts, send a phrase manually, replay the last continuation, or clear local buffers.
+- `Session Activity`: switch between `History` and `Memory`.
+
+The UX principle is to keep the performance flow visible at all times and hide lower-frequency controls behind progressive disclosure:
+
+- High-frequency controls stay on the main surface.
+- Advanced model controls live in the `Advanced Continuator Settings` drawer.
+- Memory inspection stays inside a local tabbed card rather than taking over the page.
+
+## High-Level Architecture
+
+```mermaid
+flowchart LR
+    A["Browser UI<br/>Web MIDI + piano rolls + playback"] --> B["FastAPI API"]
+    B --> C["SessionManager"]
+    C --> D["Per-session ContinuatorSessionEngine"]
+    D --> E["Vendored Continuator core"]
+    C --> F["SQLite phrase history"]
+    D --> G["Optional seed MIDI corpus"]
+```
+
+At a high level:
+
+- The browser captures raw MIDI events in real time.
+- The browser segments those events into phrases.
+- The backend converts phrase JSON into `mido.Message` objects.
+- The session-specific engine learns the phrase and samples a continuation.
+- The backend converts the result back to JSON.
+- The browser renders and plays the continuation.
+
+## Runtime Pipeline
+
+The phrase pipeline is:
+
+1. A user clicks `Connect MIDI` and chooses a browser MIDI input.
+2. The browser receives `note_on` and `note_off` events in real time.
+3. The front-end keeps a phrase open while notes are still active.
+4. A phrase closes when all notes are released and 1 second has passed since the final note event, which in practice means 1 second after the final `note_off`.
+5. The browser stores the captured phrase as JSON with timing deltas.
+6. The client sends that JSON to `POST /api/continue`.
+7. The backend reconstructs `mido.Message` objects and asks Continuator for a phrase representation.
+8. The backend follows the current Continuator strategy: learn the input phrase first, then generate.
+9. The backend returns both the input phrase and generated phrase as note-level and event-level JSON payloads.
+10. The browser updates the piano rolls, logs the interaction in `History`, refreshes `Memory`, and plays the continuation.
+
+By default, the backend asks for a continuation with the same note count as the input phrase.
+
+For robustness, the wrapper currently retries generation without the hard end constraint if the exact same-length plus exact-ending request has no solution. This helps some dense or chordal phrases without modifying the Continuator core itself.
+
+## Session Model
+
+A session is the main runtime boundary in this application.
+
+Each session contains:
+
+- One in-memory Continuator engine.
+- One current settings snapshot.
+- Logged phrase history in SQLite.
+- A live memory view derived from the engine state.
+
+Important distinction:
+
+- `History` is everything that was logged for the session.
+- `Memory` is only what is currently active inside the Continuator engine.
+
+Those are not always the same:
+
+- If `forget old phrases` is enabled, some historical phrases may no longer be active in memory.
+- If `transpose` is enabled, one learned phrase can appear as several active memory sequences.
+- If the backend is restarted, the in-memory engine is rebuilt, while SQLite history remains on disk.
+
+## Memory Model
+
+The `Memory` tab is a visualization of the active engine state for the current session.
+
+It shows:
+
+- Summary chips with the active sequence count and settings.
+- A recency ribbon from oldest to newest.
+- A list of active memory slots, newest first.
+
+The memory view is based on the Continuator engine's current `input_sequences`, not on the SQLite history log.
+
+If a seed MIDI file or folder is loaded, memory items are labeled as:
+
+- `seed`: sequences learned from the seed corpus at session initialization.
+- `live`: sequences learned from browser interaction during the session.
+
+Current limitation:
+
+- This is session memory, not yet user memory.
+- There is no persistent musical profile that follows a user across sessions.
+
+## Continuator Settings Exposed In The UI
+
+The advanced drawer currently exposes existing Continuator parameters already present in the original Gradio interface:
+
+- `Learn input`
+- `Transpose`
+- `Forget old phrases`
+- `Keep only N last inputs`
+- `Decay mode`
+
+Design choice:
+
+- `Learn input` stays visible because it directly affects performance behavior.
+- The other parameters live in the advanced drawer because they are lower-frequency controls.
+
+## Repository Layout
+
+```text
+backend/
+  app/
+    config.py
+    continuator_adapter.py
+    main.py
+    schemas.py
+    session_manager.py
+    storage.py
+  data/
+  vendor/
+frontend/
+  app.js
+  index.html
+  styles.css
+Dockerfile
+README.md
+```
+
+Main responsibilities:
+
+- `frontend/index.html`: page structure and UI regions.
+- `frontend/app.js`: MIDI capture, phrase segmentation, API calls, playback, and client-side visualization.
+- `frontend/styles.css`: layout and visual design.
+- `backend/app/main.py`: FastAPI routes.
+- `backend/app/session_manager.py`: session lifecycle, orchestration, and API-facing session logic.
+- `backend/app/continuator_adapter.py`: bridge between web JSON payloads and the Continuator Python engine.
+- `backend/app/storage.py`: SQLite session and phrase logging.
+- `backend/vendor/`: vendored Continuator code used by the web wrapper.
+
+`backend/vendor/` contains the minimal Continuator modules needed for the web path, copied from the existing local `continuator` checkout and kept under the original license in `backend/vendor/LICENSE.continuator`.
+
+## API Surface
+
+Current API endpoints:
+
+- `GET /health`: lightweight health check.
+- `GET /api/config`: public app-level configuration.
+- `POST /api/session`: create a new session and its isolated Continuator engine.
+- `PATCH /api/sessions/{session_id}/settings`: update live session settings.
+- `POST /api/continue`: send one phrase and request a continuation.
+- `GET /api/sessions/{session_id}/history`: retrieve recent logged phrase history.
+- `GET /api/sessions/{session_id}/memory`: retrieve the active memory snapshot for the live engine.
+- `POST /api/sessions/{session_id}/reset`: clear the live engine memory while preserving session settings.
+
+API payloads use JSON and expose both:
+
+- event-level timing data for playback
+- note-level timing data for visualization
+
+## Local Development
+
+Create a virtual environment, install dependencies, and launch the backend:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r backend/requirements.txt
+python -m uvicorn app.main:app --app-dir backend --reload
+```
+
+Open:
+
+```text
+http://127.0.0.1:8000
+```
+
+Recommended browser support:
+
+- Chrome
+- Edge
+
+`localhost` is a valid secure context for Web MIDI, so HTTPS is not required for local development.
+
+Typical local interaction:
+
+1. Click `Create Session`.
+2. Click `Connect MIDI`.
+3. Choose a MIDI input.
+4. Choose `Browser Synth` or a hardware output.
+5. Optionally open `Advanced Continuator Settings`.
+6. Play a phrase.
+7. Wait 1 second after the final note release.
+8. Let auto-send submit the phrase, or click `Send Phrase`.
+9. Inspect `History` or `Memory` in the `Session Activity` card.
+
+When you change frontend code, a normal refresh is usually enough.
+When you change backend models or routes, restarting the server and refreshing the page is the safest option.
+
+## Configuration
+
+Environment variables currently supported:
+
+- `CONTINUATOR_APP_NAME`: override the displayed app name.
+- `CONTINUATOR_DB_PATH`: move the SQLite database to another location.
+- `CONTINUATOR_SEED_MIDI_FILE`: preload each new session with one MIDI file.
+- `CONTINUATOR_SEED_MIDI_FOLDER`: preload each new session with a folder of MIDI files.
+- `CONTINUATOR_SOURCE_DIR`: advanced development option to import Continuator from an external checkout instead of the vendored copy.
+
+Examples:
+
+```bash
+export CONTINUATOR_SEED_MIDI_FILE=/absolute/path/to/example.mid
+export CONTINUATOR_DB_PATH=/absolute/path/to/continuator.sqlite3
+```
+
+## Optional Seed Corpus
+
+If you want each new session to start from an existing corpus instead of an empty Continuator memory, set one of the seed variables before launching the server:
+
+```bash
+export CONTINUATOR_SEED_MIDI_FILE=/absolute/path/to/example.mid
+export CONTINUATOR_SEED_MIDI_FOLDER=/absolute/path/to/midi/folder
+```
+
+This changes the starting memory of each newly created session, but sessions remain isolated from one another.
+
+## Docker
+
+Build and run locally:
+
+```bash
+docker build -t continuator-web .
+docker run --rm -p 7860:7860 continuator-web
+```
+
+Why the Docker image is simple:
+
+- The frontend is static and does not require a separate Node build.
+- The backend serves both the API and static assets.
+- The image exposes port `7860`, which matches common Hugging Face Docker Space conventions.
+
+## Deploying To Hugging Face Spaces
+
+This repository is now prepared to be used as a Docker Space.
+
+The YAML block at the top of this `README.md` declares:
+
+- `sdk: docker`
+- `app_port: 7860`
+
+Typical deployment flow:
+
+1. Create a new Space on Hugging Face.
+2. Choose the `Docker` SDK.
+3. Push this repository to the Space repository.
+4. Let the Space build automatically from the included `Dockerfile`.
+
+If you want phrase history to survive restarts, attach a storage volume or bucket and mount it at `/data` (or another path), then point the database there with an environment variable such as:
+
+```bash
+CONTINUATOR_DB_PATH=/data/continuator.sqlite3
+```
+
+If you want each new session to start from a corpus, you can also define:
+
+```bash
+CONTINUATOR_SEED_MIDI_FILE=/data/seeds/example.mid
+CONTINUATOR_SEED_MIDI_FOLDER=/data/seeds
+```
+
+For a first public demo, the simplest deployment is:
+
+- free CPU hardware
+- no persistent storage
+- no seed corpus
+
+That keeps the setup minimal and is enough to validate browser MIDI capture, API round-trips, and continuation playback.
+
+## Hugging Face Spaces Notes
+
+This repository is shaped for a Docker Space:
+
+- one container
+- static frontend
+- Python API
+- no extra frontend build pipeline
+
+That makes it a good fit for a public demo or lightweight prototype.
+
+Things to keep in mind:
+
+- The current live session registry is in process memory, so scaling to multiple replicas would require shared session storage.
+- SQLite is fine for a prototype, but PostgreSQL would be a better next step for heavier concurrent use.
+- Persistent user memory is not implemented yet.
+- Long-lived or heavier multi-user deployments will need explicit storage, authentication, and horizontal architecture decisions.
+
+## Local Mac Usage After Space Setup
+
+Yes: adding Hugging Face Space metadata does not change the local development workflow.
+
+You can still run the app exactly as before:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r backend/requirements.txt
+python -m uvicorn app.main:app --app-dir backend --reload
+```
+
+The Hugging Face YAML block is only repository metadata for the Space platform. The local frontend, backend, and Docker workflows continue to work the same way on macOS.
+
+## Current Limitations
+
+- Session engines are in memory only.
+- Memory does not survive a backend restart unless re-created from a seed corpus.
+- There is no user account layer yet.
+- The `Memory` tab shows session memory, not cross-session user memory.
+- Web MIDI support depends on browser support and user permission.
+- The Continuator core is currently treated as a black box from the web wrapper side.
+
+## Roadmap Ideas
+
+Natural next steps for this project:
+
+- Persistent per-user memory across sessions.
+- Authentication or signed session tokens.
+- A shared session store for multi-instance deployments.
+- PostgreSQL instead of SQLite when concurrent writes matter.
+- Inline piano-roll thumbnails in the `Memory` list.
+- Stronger observability for generation behavior and debugging.
+- A richer corpus management workflow for seed material.

backend/app/__init__.py

@@ -0,0 +1,2 @@
+"""Continuator web backend package."""
+

backend/app/config.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import os
+
+
+BACKEND_DIR = Path(__file__).resolve().parents[1]
+PROJECT_DIR = BACKEND_DIR.parent
+FRONTEND_DIR = PROJECT_DIR / "frontend"
+DATA_DIR = BACKEND_DIR / "data"
+VENDOR_DIR = BACKEND_DIR / "vendor"
+
+
+@dataclass(frozen=True)
+class Settings:
+    app_name: str
+    frontend_dir: Path
+    vendor_dir: Path
+    db_path: Path
+    seed_midi_file: Path | None
+    seed_midi_folder: Path | None
+
+
+def _env_path(name: str) -> Path | None:
+    raw = os.getenv(name)
+    if not raw:
+        return None
+    return Path(raw).expanduser()
+
+
+def load_settings() -> Settings:
+    return Settings(
+        app_name=os.getenv("CONTINUATOR_APP_NAME", "Continuator Web"),
+        frontend_dir=FRONTEND_DIR,
+        vendor_dir=VENDOR_DIR,
+        db_path=_env_path("CONTINUATOR_DB_PATH") or (DATA_DIR / "continuator.sqlite3"),
+        seed_midi_file=_env_path("CONTINUATOR_SEED_MIDI_FILE"),
+        seed_midi_folder=_env_path("CONTINUATOR_SEED_MIDI_FOLDER"),
+    )
+

backend/app/continuator_adapter.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+from pathlib import Path
+import os
+import sys
+import threading
+
+import mido
+
+from .schemas import MidiEvent, PhraseNote, PhrasePayload, PlaybackMidiEvent
+
+
+BACKEND_DIR = Path(__file__).resolve().parents[1]
+VENDOR_DIR = BACKEND_DIR / "vendor"
+
+
+def _bootstrap_continuator_imports() -> None:
+    candidate_paths: list[Path] = []
+    external_source = os.getenv("CONTINUATOR_SOURCE_DIR")
+    if external_source:
+        candidate_paths.append(Path(external_source).expanduser())
+    candidate_paths.append(VENDOR_DIR)
+
+    for path in candidate_paths:
+        if path.exists():
+            resolved = str(path)
+            if resolved not in sys.path:
+                sys.path.insert(0, resolved)
+            return
+
+    raise RuntimeError("Could not locate Continuator source files.")
+
+
+_bootstrap_continuator_imports()
+
+from ctor.continuator import Continuator2  # noqa: E402
+
+
+class NoContinuationAvailable(RuntimeError):
+    """Raised when the engine cannot generate a continuation."""
+
+
+def _round_float(value: float) -> float:
+    return round(float(value), 6)
+
+
+def _normalize_notes(notes: list[object]) -> list[object]:
+    normalized = [note.copy() if hasattr(note, "copy") else note for note in notes]
+    if not normalized:
+        return normalized
+
+    min_start = min(float(note.start_time) for note in normalized)
+    if min_start < 0:
+        for note in normalized:
+            note.start_time = float(note.start_time) - min_start
+
+    normalized.sort(key=lambda note: (float(note.start_time), int(note.pitch), float(note.duration)))
+    return normalized
+
+
+def _note_to_schema(note: object) -> PhraseNote:
+    start_seconds = _round_float(note.start_time / 2.0)
+    duration_seconds = _round_float(note.duration / 2.0)
+    end_seconds = _round_float(start_seconds + duration_seconds)
+    return PhraseNote(
+        pitch=int(note.pitch),
+        velocity=int(note.velocity),
+        start_seconds=start_seconds,
+        duration_seconds=duration_seconds,
+        end_seconds=end_seconds,
+        start_beats=_round_float(note.start_time),
+        duration_beats=_round_float(note.duration),
+    )
+
+
+def _notes_to_events(notes: list[object]) -> list[PlaybackMidiEvent]:
+    timed_events: list[dict[str, float | int | str]] = []
+    for note in notes:
+        start_seconds = note.start_time / 2.0
+        end_seconds = (note.start_time + note.duration) / 2.0
+        timed_events.append(
+            {
+                "type": "note_on",
+                "note": int(note.pitch),
+                "velocity": int(note.velocity),
+                "channel": 0,
+                "time_seconds": start_seconds,
+            }
+        )
+        timed_events.append(
+            {
+                "type": "note_off",
+                "note": int(note.pitch),
+                "velocity": 0,
+                "channel": 0,
+                "time_seconds": end_seconds,
+            }
+        )
+
+    timed_events.sort(
+        key=lambda item: (
+            float(item["time_seconds"]),
+            0 if item["type"] == "note_off" else 1,
+            int(item["note"]),
+        )
+    )
+
+    events: list[PlaybackMidiEvent] = []
+    current_time = 0.0
+    for item in timed_events:
+        absolute_time = _round_float(float(item["time_seconds"]))
+        delta = _round_float(max(0.0, absolute_time - current_time))
+        current_time = absolute_time
+        events.append(
+            PlaybackMidiEvent(
+                type=str(item["type"]),
+                note=int(item["note"]),
+                velocity=int(item["velocity"]),
+                channel=int(item["channel"]),
+                delta_seconds=delta,
+                time_seconds=absolute_time,
+            )
+        )
+
+    return events
+
+
+def _build_phrase_payload(notes: list[object]) -> PhrasePayload:
+    normalized_notes = _normalize_notes(notes)
+    note_payload = [_note_to_schema(note) for note in normalized_notes]
+    events = _notes_to_events(normalized_notes)
+    duration_seconds = max((note.end_seconds for note in note_payload), default=0.0)
+
+    return PhrasePayload(
+        event_count=len(events),
+        note_count=len(note_payload),
+        duration_seconds=_round_float(duration_seconds),
+        events=events,
+        notes=note_payload,
+    )
+
+
+def _event_to_mido_message(event: MidiEvent) -> mido.Message:
+    velocity = event.velocity if event.type == "note_on" else 0
+    return mido.Message(
+        event.type,
+        note=event.note,
+        velocity=velocity,
+        channel=event.channel,
+        time=float(event.delta_seconds),
+    )
+
+
+class ContinuatorSessionEngine:
+    def __init__(
+        self,
+        learn_input: bool = True,
+        transposition: bool = False,
+        forget_past: bool = False,
+        keep_last_inputs: int = 20,
+        decay_mode: str = "full",
+        seed_midi_file: Path | None = None,
+        seed_midi_folder: Path | None = None,
+    ) -> None:
+        self._default_learn_input = learn_input
+        self._transposition = transposition
+        self._forget_past = forget_past
+        self._keep_last_inputs = keep_last_inputs
+        self._decay_mode = decay_mode
+        self._seed_midi_file = seed_midi_file
+        self._seed_midi_folder = seed_midi_folder
+        self._seed_sequence_count = 0
+        self._lock = threading.RLock()
+        self._continuator = self._create_engine()
+
+    def _create_engine(self) -> Continuator2:
+        midi_file = str(self._seed_midi_file) if self._seed_midi_file else None
+        engine = Continuator2(midi_file=midi_file, transposition=self._transposition)
+        if self._seed_midi_folder:
+            engine.learn_folder(str(self._seed_midi_folder), transpose=self._transposition)
+        engine.set_learn_input(self._default_learn_input)
+        engine.set_transpose(self._transposition)
+        engine.set_forget(self._forget_past)
+        engine.set_keep_last(self._keep_last_inputs)
+        engine.set_decay_mode(self._decay_mode)
+        self._seed_sequence_count = len(getattr(engine.vom, "input_sequences", []))
+        return engine
+
+    def apply_settings(
+        self,
+        *,
+        learn_input: bool | None = None,
+        transposition: bool | None = None,
+        forget_past: bool | None = None,
+        keep_last_inputs: int | None = None,
+        decay_mode: str | None = None,
+    ) -> None:
+        with self._lock:
+            if learn_input is not None:
+                self._default_learn_input = learn_input
+                self._continuator.set_learn_input(learn_input)
+            if transposition is not None:
+                self._transposition = transposition
+                self._continuator.set_transpose(transposition)
+            if forget_past is not None:
+                self._forget_past = forget_past
+                self._continuator.set_forget(forget_past)
+            if keep_last_inputs is not None:
+                self._keep_last_inputs = keep_last_inputs
+                self._continuator.set_keep_last(keep_last_inputs)
+            if decay_mode is not None:
+                self._decay_mode = decay_mode
+                self._continuator.set_decay_mode(decay_mode)
+
+    def reset(self) -> None:
+        with self._lock:
+            self._continuator = self._create_engine()
+
+    def get_memory_snapshot(self) -> tuple[list[PhrasePayload], int]:
+        with self._lock:
+            sequences = list(getattr(self._continuator.vom, "input_sequences", []))
+            payloads = [_build_phrase_payload(sequence) for sequence in sequences]
+            seed_count = min(self._seed_sequence_count, len(payloads))
+            return payloads, seed_count
+
+    def continue_phrase(
+        self,
+        phrase_events: list[MidiEvent],
+        learn_input: bool | None = None,
+        continuation_note_count: int | None = None,
+    ) -> tuple[PhrasePayload, PhrasePayload, str | None]:
+        with self._lock:
+            messages = [_event_to_mido_message(event) for event in phrase_events]
+            input_phrase = self._continuator.get_phrase_from_mido(messages)
+            if not input_phrase:
+                raise NoContinuationAvailable("The incoming phrase did not contain any complete notes.")
+
+            should_learn = self._default_learn_input if learn_input is None else learn_input
+            input_payload = _build_phrase_payload(input_phrase)
+            target_note_count = continuation_note_count or len(input_phrase)
+
+            if should_learn:
+                self._continuator.learn_phrase(input_phrase, self._continuator.transpose)
+
+            status_message = None
+            constraints = {target_note_count: self._continuator.get_end_vp()}
+            generated_sequence = self._continuator.sample_sequence(
+                prefix=input_phrase,
+                length=target_note_count + 1,
+                constraints=constraints,
+            )
+            if generated_sequence is None:
+                generated_sequence = self._continuator.sample_sequence(
+                    prefix=input_phrase,
+                    length=target_note_count,
+                    constraints={},
+                )
+                status_message = (
+                    "Used a same-length continuation without the hard end constraint "
+                    "because the exact-ending version had no solution."
+                )
+
+            if generated_sequence is None:
+                raise NoContinuationAvailable("The Continuator could not find a valid continuation.")
+
+            rendered_vp_sequence = generated_sequence
+            if rendered_vp_sequence and rendered_vp_sequence[-1] == self._continuator.get_end_vp():
+                rendered_vp_sequence = rendered_vp_sequence[:-1]
+
+            rendered_sequence = self._continuator.realize_vp_sequence(rendered_vp_sequence)
+            return input_payload, _build_phrase_payload(rendered_sequence), status_message

backend/app/main.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from .config import load_settings
+from .schemas import (
+    ContinueRequest,
+    ContinueResponse,
+    CreateSessionRequest,
+    CreateSessionResponse,
+    PublicConfigResponse,
+    ResetSessionResponse,
+    SessionHistoryResponse,
+    SessionMemoryResponse,
+    UpdateSessionSettingsRequest,
+    UpdateSessionSettingsResponse,
+)
+from .session_manager import NoContinuationAvailable, SessionManager, UnknownSessionError
+from .storage import PhraseStorage
+
+
+settings = load_settings()
+storage = PhraseStorage(settings.db_path)
+session_manager = SessionManager(
+    storage=storage,
+    seed_midi_file=settings.seed_midi_file,
+    seed_midi_folder=settings.seed_midi_folder,
+)
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version="0.1.0",
+    description=(
+        "A lightweight web wrapper around François Pachet's Continuator, with "
+        "browser-side MIDI capture, session-isolated engines, and SQLite logging."
+    ),
+)
+
+app.mount("/assets", StaticFiles(directory=settings.frontend_dir), name="assets")
+
+
+@app.get("/", include_in_schema=False)
+def read_index() -> FileResponse:
+    return FileResponse(settings.frontend_dir / "index.html")
+
+
+@app.get("/health", tags=["system"])
+def healthcheck() -> dict[str, object]:
+    return {
+        "ok": True,
+        "app_name": settings.app_name,
+        "seeded": session_manager.seeded,
+    }
+
+
+@app.get("/api/config", response_model=PublicConfigResponse, tags=["system"])
+def public_config() -> PublicConfigResponse:
+    return PublicConfigResponse(
+        app_name=settings.app_name,
+        seeded=session_manager.seeded,
+    )
+
+
+@app.post("/api/session", response_model=CreateSessionResponse, tags=["session"])
+def create_session(payload: CreateSessionRequest) -> CreateSessionResponse:
+    return session_manager.create_session(payload)
+
+
+@app.patch(
+    "/api/sessions/{session_id}/settings",
+    response_model=UpdateSessionSettingsResponse,
+    tags=["session"],
+)
+def update_session_settings(
+    session_id: str,
+    payload: UpdateSessionSettingsRequest,
+) -> UpdateSessionSettingsResponse:
+    try:
+        return session_manager.update_session_settings(session_id, payload)
+    except UnknownSessionError as error:
+        raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error
+
+
+@app.post("/api/continue", response_model=ContinueResponse, tags=["continuator"])
+def continue_phrase(payload: ContinueRequest) -> ContinueResponse:
+    try:
+        return session_manager.continue_phrase(payload)
+    except UnknownSessionError as error:
+        raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error
+    except NoContinuationAvailable as error:
+        raise HTTPException(status_code=409, detail=str(error)) from error
+
+
+@app.get(
+    "/api/sessions/{session_id}/history",
+    response_model=SessionHistoryResponse,
+    tags=["session"],
+)
+def session_history(
+    session_id: str,
+    limit: int = Query(default=12, ge=1, le=100),
+) -> SessionHistoryResponse:
+    try:
+        return session_manager.get_history(session_id, limit=limit)
+    except UnknownSessionError as error:
+        raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error
+
+
+@app.get(
+    "/api/sessions/{session_id}/memory",
+    response_model=SessionMemoryResponse,
+    tags=["session"],
+)
+def session_memory(session_id: str) -> SessionMemoryResponse:
+    try:
+        return session_manager.get_memory(session_id)
+    except UnknownSessionError as error:
+        raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error
+
+
+@app.post(
+    "/api/sessions/{session_id}/reset",
+    response_model=ResetSessionResponse,
+    tags=["session"],
+)
+def reset_session(session_id: str) -> ResetSessionResponse:
+    try:
+        return session_manager.reset_session(session_id)
+    except UnknownSessionError as error:
+        raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error

backend/app/schemas.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+DecayMode = Literal["full", "late", "middle", "early"]
+MemoryPhraseSource = Literal["seed", "live"]
+
+
+class MidiEvent(BaseModel):
+    type: Literal["note_on", "note_off"]
+    note: int = Field(ge=0, le=127)
+    velocity: int = Field(ge=0, le=127)
+    channel: int = Field(default=0, ge=0, le=15)
+    delta_seconds: float = Field(ge=0.0)
+
+
+class PlaybackMidiEvent(MidiEvent):
+    time_seconds: float = Field(ge=0.0)
+
+
+class PhraseNote(BaseModel):
+    pitch: int = Field(ge=0, le=127)
+    velocity: int = Field(ge=0, le=127)
+    start_seconds: float = Field(ge=0.0)
+    duration_seconds: float = Field(ge=0.0)
+    end_seconds: float = Field(ge=0.0)
+    start_beats: float = Field(ge=0.0)
+    duration_beats: float = Field(ge=0.0)
+
+
+class PhrasePayload(BaseModel):
+    event_count: int = Field(ge=0)
+    note_count: int = Field(ge=0)
+    duration_seconds: float = Field(ge=0.0)
+    events: list[PlaybackMidiEvent]
+    notes: list[PhraseNote]
+
+
+class CreateSessionRequest(BaseModel):
+    learn_input: bool = True
+    transposition: bool = False
+    forget_past: bool = False
+    keep_last_inputs: int = Field(default=20, ge=1, le=500)
+    decay_mode: DecayMode = "full"
+
+
+class SessionConfiguration(BaseModel):
+    learn_input: bool
+    transposition: bool
+    forget_past: bool
+    keep_last_inputs: int = Field(ge=1, le=500)
+    decay_mode: DecayMode
+    seeded: bool
+
+
+class CreateSessionResponse(BaseModel):
+    session_id: str
+    created_at: str
+    configuration: SessionConfiguration
+
+
+class ContinueRequest(BaseModel):
+    session_id: str = Field(min_length=1)
+    phrase: list[MidiEvent] = Field(min_length=1)
+    learn_input: bool | None = None
+    continuation_note_count: int | None = Field(default=None, ge=1)
+
+
+class ContinueResponse(BaseModel):
+    session_id: str
+    request_id: str
+    created_at: str
+    input_phrase: PhrasePayload
+    generated_phrase: PhrasePayload
+    status_message: str | None = None
+
+
+class HistoryItem(BaseModel):
+    id: str
+    request_id: str
+    kind: Literal["input", "generated"]
+    created_at: str
+    event_count: int = Field(ge=0)
+    note_count: int = Field(ge=0)
+    duration_seconds: float = Field(ge=0.0)
+    payload: PhrasePayload
+
+
+class SessionHistoryResponse(BaseModel):
+    session_id: str
+    items: list[HistoryItem]
+
+
+class MemoryPhraseItem(BaseModel):
+    slot: int = Field(ge=1)
+    source: MemoryPhraseSource
+    event_count: int = Field(ge=0)
+    note_count: int = Field(ge=0)
+    duration_seconds: float = Field(ge=0.0)
+    payload: PhrasePayload
+
+
+class SessionMemorySummary(BaseModel):
+    active_phrase_count: int = Field(ge=0)
+    seeded_phrase_count: int = Field(ge=0)
+    live_phrase_count: int = Field(ge=0)
+
+
+class SessionMemoryResponse(BaseModel):
+    session_id: str
+    configuration: SessionConfiguration
+    summary: SessionMemorySummary
+    items: list[MemoryPhraseItem]
+
+
+class ResetSessionResponse(BaseModel):
+    session_id: str
+    reset_at: str
+    configuration: SessionConfiguration
+
+
+class UpdateSessionSettingsRequest(BaseModel):
+    learn_input: bool | None = None
+    transposition: bool | None = None
+    forget_past: bool | None = None
+    keep_last_inputs: int | None = Field(default=None, ge=1, le=500)
+    decay_mode: DecayMode | None = None
+
+
+class UpdateSessionSettingsResponse(BaseModel):
+    session_id: str
+    updated_at: str
+    configuration: SessionConfiguration
+
+
+class PublicConfigResponse(BaseModel):
+    app_name: str
+    seeded: bool

backend/app/session_manager.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+import threading
+import uuid
+
+from .continuator_adapter import ContinuatorSessionEngine, NoContinuationAvailable
+from .schemas import (
+    ContinueRequest,
+    ContinueResponse,
+    CreateSessionRequest,
+    CreateSessionResponse,
+    HistoryItem,
+    MemoryPhraseItem,
+    ResetSessionResponse,
+    SessionConfiguration,
+    SessionHistoryResponse,
+    SessionMemoryResponse,
+    SessionMemorySummary,
+    UpdateSessionSettingsRequest,
+    UpdateSessionSettingsResponse,
+)
+from .storage import PhraseStorage
+
+
+class UnknownSessionError(KeyError):
+    """Raised when a session identifier is unknown."""
+
+
+def utc_now_iso() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+@dataclass
+class SessionState:
+    session_id: str
+    created_at: str
+    last_seen_at: str
+    configuration: SessionConfiguration
+    engine: ContinuatorSessionEngine
+
+
+class SessionManager:
+    def __init__(
+        self,
+        storage: PhraseStorage,
+        seed_midi_file: Path | None = None,
+        seed_midi_folder: Path | None = None,
+    ) -> None:
+        self.storage = storage
+        self.seed_midi_file = seed_midi_file
+        self.seed_midi_folder = seed_midi_folder
+        self._sessions: dict[str, SessionState] = {}
+        self._lock = threading.RLock()
+
+    @property
+    def seeded(self) -> bool:
+        return bool(self.seed_midi_file or self.seed_midi_folder)
+
+    def create_session(self, request: CreateSessionRequest) -> CreateSessionResponse:
+        created_at = utc_now_iso()
+        session_id = uuid.uuid4().hex
+        configuration = SessionConfiguration(
+            learn_input=request.learn_input,
+            transposition=request.transposition,
+            forget_past=request.forget_past,
+            keep_last_inputs=request.keep_last_inputs,
+            decay_mode=request.decay_mode,
+            seeded=self.seeded,
+        )
+        engine = ContinuatorSessionEngine(
+            learn_input=request.learn_input,
+            transposition=request.transposition,
+            forget_past=request.forget_past,
+            keep_last_inputs=request.keep_last_inputs,
+            decay_mode=request.decay_mode,
+            seed_midi_file=self.seed_midi_file,
+            seed_midi_folder=self.seed_midi_folder,
+        )
+        state = SessionState(
+            session_id=session_id,
+            created_at=created_at,
+            last_seen_at=created_at,
+            configuration=configuration,
+            engine=engine,
+        )
+
+        with self._lock:
+            self._sessions[session_id] = state
+
+        self.storage.create_session(
+            session_id=session_id,
+            created_at=created_at,
+            metadata=configuration.model_dump(),
+        )
+        return CreateSessionResponse(
+            session_id=session_id,
+            created_at=created_at,
+            configuration=configuration,
+        )
+
+    def _require_session(self, session_id: str) -> SessionState:
+        with self._lock:
+            session = self._sessions.get(session_id)
+        if session is None:
+            raise UnknownSessionError(session_id)
+        return session
+
+    def continue_phrase(self, request: ContinueRequest) -> ContinueResponse:
+        state = self._require_session(request.session_id)
+        created_at = utc_now_iso()
+        request_id = uuid.uuid4().hex
+        input_phrase, generated_phrase, status_message = state.engine.continue_phrase(
+            request.phrase,
+            learn_input=request.learn_input,
+            continuation_note_count=request.continuation_note_count,
+        )
+
+        state.last_seen_at = created_at
+        self.storage.touch_session(state.session_id, created_at)
+        self.storage.log_phrase(
+            phrase_id=uuid.uuid4().hex,
+            request_id=request_id,
+            session_id=state.session_id,
+            kind="input",
+            created_at=created_at,
+            payload=input_phrase.model_dump(mode="json"),
+        )
+        self.storage.log_phrase(
+            phrase_id=uuid.uuid4().hex,
+            request_id=request_id,
+            session_id=state.session_id,
+            kind="generated",
+            created_at=created_at,
+            payload=generated_phrase.model_dump(mode="json"),
+        )
+
+        return ContinueResponse(
+            session_id=state.session_id,
+            request_id=request_id,
+            created_at=created_at,
+            input_phrase=input_phrase,
+            generated_phrase=generated_phrase,
+            status_message=status_message,
+        )
+
+    def get_history(self, session_id: str, limit: int = 20) -> SessionHistoryResponse:
+        if not self.storage.session_exists(session_id):
+            raise UnknownSessionError(session_id)
+        items = [
+            HistoryItem.model_validate(item)
+            for item in self.storage.get_history(session_id, limit=limit)
+        ]
+        return SessionHistoryResponse(session_id=session_id, items=items)
+
+    def get_memory(self, session_id: str) -> SessionMemoryResponse:
+        state = self._require_session(session_id)
+        payloads, seeded_count = state.engine.get_memory_snapshot()
+        items = [
+            MemoryPhraseItem(
+                slot=index + 1,
+                source="seed" if index < seeded_count else "live",
+                event_count=payload.event_count,
+                note_count=payload.note_count,
+                duration_seconds=payload.duration_seconds,
+                payload=payload,
+            )
+            for index, payload in enumerate(payloads)
+        ]
+        summary = SessionMemorySummary(
+            active_phrase_count=len(items),
+            seeded_phrase_count=seeded_count,
+            live_phrase_count=max(0, len(items) - seeded_count),
+        )
+        return SessionMemoryResponse(
+            session_id=session_id,
+            configuration=state.configuration,
+            summary=summary,
+            items=items,
+        )
+
+    def reset_session(self, session_id: str) -> ResetSessionResponse:
+        state = self._require_session(session_id)
+        state.engine.reset()
+        state.last_seen_at = utc_now_iso()
+        self.storage.touch_session(session_id, state.last_seen_at)
+        return ResetSessionResponse(
+            session_id=session_id,
+            reset_at=state.last_seen_at,
+            configuration=state.configuration,
+        )
+
+    def update_session_settings(
+        self,
+        session_id: str,
+        request: UpdateSessionSettingsRequest,
+    ) -> UpdateSessionSettingsResponse:
+        state = self._require_session(session_id)
+        updated_at = utc_now_iso()
+
+        update_fields = request.model_dump(exclude_none=True)
+        if not update_fields:
+            return UpdateSessionSettingsResponse(
+                session_id=session_id,
+                updated_at=updated_at,
+                configuration=state.configuration,
+            )
+
+        state.engine.apply_settings(**update_fields)
+        state.configuration = state.configuration.model_copy(update=update_fields)
+        state.last_seen_at = updated_at
+        self.storage.update_session_metadata(
+            session_id=session_id,
+            metadata=state.configuration.model_dump(),
+            last_seen_at=updated_at,
+        )
+        return UpdateSessionSettingsResponse(
+            session_id=session_id,
+            updated_at=updated_at,
+            configuration=state.configuration,
+        )
+
+
+__all__ = [
+    "NoContinuationAvailable",
+    "SessionManager",
+    "UnknownSessionError",
+]

backend/app/storage.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from pathlib import Path
+import json
+import sqlite3
+import threading
+
+
+SCHEMA_SQL = """
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    created_at TEXT NOT NULL,
+    last_seen_at TEXT NOT NULL,
+    metadata_json TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS phrases (
+    id TEXT PRIMARY KEY,
+    request_id TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    kind TEXT NOT NULL CHECK(kind IN ('input', 'generated')),
+    created_at TEXT NOT NULL,
+    event_count INTEGER NOT NULL,
+    note_count INTEGER NOT NULL,
+    duration_seconds REAL NOT NULL,
+    payload_json TEXT NOT NULL,
+    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_phrases_session_created
+    ON phrases(session_id, created_at DESC);
+"""
+
+
+class PhraseStorage:
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(self.db_path, check_same_thread=False)
+        connection.row_factory = sqlite3.Row
+        return connection
+
+    def _initialize(self) -> None:
+        with self._lock, self._connect() as connection:
+            connection.executescript(SCHEMA_SQL)
+
+    def create_session(self, session_id: str, created_at: str, metadata: dict[str, object]) -> None:
+        payload = json.dumps(metadata, ensure_ascii=False)
+        with self._lock, self._connect() as connection:
+            connection.execute(
+                """
+                INSERT OR REPLACE INTO sessions (id, created_at, last_seen_at, metadata_json)
+                VALUES (?, ?, ?, ?)
+                """,
+                (session_id, created_at, created_at, payload),
+            )
+            connection.commit()
+
+    def touch_session(self, session_id: str, last_seen_at: str) -> None:
+        with self._lock, self._connect() as connection:
+            connection.execute(
+                "UPDATE sessions SET last_seen_at = ? WHERE id = ?",
+                (last_seen_at, session_id),
+            )
+            connection.commit()
+
+    def update_session_metadata(
+        self,
+        session_id: str,
+        metadata: dict[str, object],
+        last_seen_at: str | None = None,
+    ) -> None:
+        payload = json.dumps(metadata, ensure_ascii=False)
+        with self._lock, self._connect() as connection:
+            if last_seen_at is None:
+                connection.execute(
+                    "UPDATE sessions SET metadata_json = ? WHERE id = ?",
+                    (payload, session_id),
+                )
+            else:
+                connection.execute(
+                    """
+                    UPDATE sessions
+                    SET metadata_json = ?, last_seen_at = ?
+                    WHERE id = ?
+                    """,
+                    (payload, last_seen_at, session_id),
+                )
+            connection.commit()
+
+    def session_exists(self, session_id: str) -> bool:
+        with self._lock, self._connect() as connection:
+            row = connection.execute(
+                "SELECT 1 FROM sessions WHERE id = ? LIMIT 1",
+                (session_id,),
+            ).fetchone()
+        return row is not None
+
+    def log_phrase(
+        self,
+        phrase_id: str,
+        request_id: str,
+        session_id: str,
+        kind: str,
+        created_at: str,
+        payload: dict[str, object],
+    ) -> None:
+        serialized_payload = json.dumps(payload, ensure_ascii=False)
+        event_count = int(payload.get("event_count", 0))
+        note_count = int(payload.get("note_count", 0))
+        duration_seconds = float(payload.get("duration_seconds", 0.0))
+
+        with self._lock, self._connect() as connection:
+            connection.execute(
+                """
+                INSERT INTO phrases (
+                    id,
+                    request_id,
+                    session_id,
+                    kind,
+                    created_at,
+                    event_count,
+                    note_count,
+                    duration_seconds,
+                    payload_json
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    phrase_id,
+                    request_id,
+                    session_id,
+                    kind,
+                    created_at,
+                    event_count,
+                    note_count,
+                    duration_seconds,
+                    serialized_payload,
+                ),
+            )
+            connection.commit()
+
+    def get_history(self, session_id: str, limit: int = 20) -> list[dict[str, object]]:
+        with self._lock, self._connect() as connection:
+            rows = connection.execute(
+                """
+                SELECT
+                    id,
+                    request_id,
+                    kind,
+                    created_at,
+                    event_count,
+                    note_count,
+                    duration_seconds,
+                    payload_json
+                FROM phrases
+                WHERE session_id = ?
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (session_id, limit),
+            ).fetchall()
+
+        return [
+            {
+                "id": row["id"],
+                "request_id": row["request_id"],
+                "kind": row["kind"],
+                "created_at": row["created_at"],
+                "event_count": row["event_count"],
+                "note_count": row["note_count"],
+                "duration_seconds": row["duration_seconds"],
+                "payload": json.loads(row["payload_json"]),
+            }
+            for row in rows
+        ]

backend/data/.gitkeep

@@ -0,0 +1 @@
+

backend/requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.115,<1
+uvicorn[standard]>=0.30,<1
+pydantic>=2.7,<3
+numpy>=2.0,<3
+mido>=1.3,<2
+

backend/vendor/LICENSE.continuator

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ynosound
+
+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.

backend/vendor/ctor/belief_propag.py

@@ -0,0 +1,320 @@
+import numpy as np
+from collections import namedtuple
+
+
+class NoSolutionErrorInBP(Exception):
+    def __init__(self, message):
+        self.message = message
+
+
+# code by Jessica Stringham:
+# https://jessicastringham.net/2019/01/09/sum-product-message-passing/
+
+LabeledArray = namedtuple(
+    "LabeledArray",
+    [
+        "array",
+        "axes_labels",
+    ],
+)
+
+
+def name_to_axis_mapping(labeled_array):
+    return {name: axis for axis, name in enumerate(labeled_array.axes_labels)}
+
+
+def other_axes_from_labeled_axes(labeled_array, axis_label):
+    # returns the indexes of the axes that are not axis label
+    return tuple(
+        axis
+        for axis, name in enumerate(labeled_array.axes_labels)
+        if name != axis_label
+    )
+
+
+def is_conditional_prob(labeled_array, var_name):
+    """
+    labeled_array (LabeledArray)
+    variable (str): name of variable, i.e. 'a' in p(a|b)
+    """
+    return np.all(
+        np.isclose(
+            np.sum(
+                labeled_array.array, axis=name_to_axis_mapping(labeled_array)[var_name]
+            ),
+            1.0,
+        )
+    )
+
+
+def is_joint_prob(labeled_array):
+    return np.all(np.isclose(np.sum(labeled_array.array), 1.0))
+
+
+def tile_to_shape_along_axis(arr, target_shape, target_axis):
+    # get a list of all axes
+    raw_axes = list(range(len(target_shape)))
+    tile_dimensions = [target_shape[a] for a in raw_axes if a != target_axis]
+    if len(arr.shape) == 0:
+        # If given a scalar, also tile it in the target dimension (so it's a bunch of 1s)
+        tile_dimensions += [target_shape[target_axis]]
+    elif len(arr.shape) == 1:
+        # If given an array, it should be the same shape as the target axis
+        assert arr.shape[0] == target_shape[target_axis]
+        tile_dimensions += [1]
+    else:
+        raise NotImplementedError()
+    tiled = np.tile(arr, tile_dimensions)
+
+    # Tiling only adds prefix axes, so rotate this one back into place
+    shifted_axes = raw_axes[:target_axis] + [raw_axes[-1]] + raw_axes[target_axis:-1]
+    transposed = np.transpose(tiled, shifted_axes)
+
+    # Double-check this code tiled it to the correct shape
+    assert transposed.shape == target_shape
+    return transposed
+
+
+def tile_to_other_dist_along_axis_name(tiling_labeled_array, target_array):
+    assert len(tiling_labeled_array.axes_labels) == 1
+    target_axis_label = tiling_labeled_array.axes_labels[0]
+
+    return LabeledArray(
+        tile_to_shape_along_axis(
+            tiling_labeled_array.array,
+            target_array.array.shape,
+            name_to_axis_mapping(target_array)[target_axis_label],
+        ),
+        axes_labels=target_array.axes_labels,
+    )
+
+
+class Node(object):
+    def __init__(self, name):
+        self.name = name
+        self.neighbors = []
+
+    def __repr__(self):
+        return "{classname}({name}, [{neighbors}])".format(
+            classname=type(self).__name__,
+            name=self.name,
+            neighbors=", ".join([n.name for n in self.neighbors]),
+        )
+
+    def is_valid_neighbor(self, neighbor):
+        raise NotImplemented()
+
+    def add_neighbor(self, neighbor):
+        assert self.is_valid_neighbor(neighbor)
+        self.neighbors.append(neighbor)
+
+
+class Variable(Node):
+    def is_valid_neighbor(self, factor):
+        return isinstance(factor, Factor)  # Variables can only neighbor Factors
+
+
+class Factor(Node):
+    def is_valid_neighbor(self, variable):
+        return isinstance(variable, Variable)  # Factors can only neighbor Variables
+
+    def __init__(self, name):
+        super(Factor, self).__init__(name)
+        self.data = None
+
+
+ParsedTerm = namedtuple(
+    "ParsedTerm",
+    [
+        "term",
+        "var_name",
+        "given",
+    ],
+)
+
+
+def _parse_term(term):
+    # Given a term like (a|b,c), returns a list of variables
+    # and conditioned-on variables
+    assert term[0] == "(" and term[-1] == ")"
+    term_variables = term[1:-1]
+
+    # Handle conditionals
+    if "|" in term_variables:
+        var, given = term_variables.split("|")
+        given = given.split(",")
+    else:
+        var = term_variables
+        given = []
+
+    return var, given
+
+
+def _parse_model_string_into_terms(model_string):
+    return [
+        ParsedTerm("p" + term, *_parse_term(term))
+        for term in model_string.split("p")
+        if term
+    ]
+
+
+def parse_model_into_variables_and_factors(model_string):
+    # Takes in a model_string such as p(h1)p(h2∣h1)p(v1∣h1)p(v2∣h2) and returns a
+    # dictionary of variable names to variables and a list of factors.
+
+    # Split model_string into ParsedTerms
+    parsed_terms = _parse_model_string_into_terms(model_string)
+
+    # First, extract all of the variables from the model_string (h1, h2, v1, v2).
+    # These each will be a new Variable that are referenced from Factors below.
+    variables = {}
+    for parsed_term in parsed_terms:
+        # if the variable name wasn't seen yet, add it to the variables dict
+        if parsed_term.var_name not in variables:
+            variables[parsed_term.var_name] = Variable(parsed_term.var_name)
+
+    # Now extract factors from the model. Each term (e.g. "p(v1|h1)") corresponds to
+    # a factor.
+    # Then find all variables in this term ("v1", "h1") and add the corresponding Variables
+    # as neighbors to the new Factor, and this Factor to the Variables' neighbors.
+    factors = []
+    for parsed_term in parsed_terms:
+        # This factor will be neighbors with all "variables" (left-hand side variables) and given variables
+        new_factor = Factor(parsed_term.term)
+        all_var_names = [parsed_term.var_name] + parsed_term.given
+        for var_name in all_var_names:
+            new_factor.add_neighbor(variables[var_name])
+            variables[var_name].add_neighbor(new_factor)
+        factors.append(new_factor)
+
+    return factors, variables
+
+
+class PGM(object):
+    def __init__(self, factors, variables):
+        self._factors = factors
+        self._variables = variables
+
+    @classmethod
+    def from_string(cls, model_string):
+        factors, variables = parse_model_into_variables_and_factors(model_string)
+        return PGM(factors, variables)
+
+    def set_data(self, data):
+        # Keep track of variable dimensions to check for shape mistakes
+        var_dims = {}
+        for factor in self._factors:
+            factor_data = data[factor.name]
+
+            if set(factor_data.axes_labels) != set(v.name for v in factor.neighbors):
+                missing_axes = set(v.name for v in factor.neighbors) - set(
+                    data[factor.name].axes_labels
+                )
+                raise ValueError(
+                    "data[{}] is missing axes: {}".format(factor.name, missing_axes)
+                )
+
+            for var_name, dim in zip(factor_data.axes_labels, factor_data.array.shape):
+                if var_name not in var_dims:
+                    var_dims[var_name] = dim
+
+                if var_dims[var_name] != dim:
+                    raise ValueError(
+                        "data[{}] axes is wrong size, {}. Expected {}".format(
+                            factor.name, dim, var_dims[var_name]
+                        )
+                    )
+
+            factor.data = data[factor.name]
+
+    def variable_from_name(self, var_name):
+        return self._variables[var_name]
+
+    def factor_from_name(self, fac_name):
+        for f in self._factors:
+            if f.name == fac_name:
+                return f
+        print(f"factor not found: {fac_name}")
+        return None
+
+    def print_marginals(self):
+        for var in self._variables.values():
+            print(f"marginal: {var.name}: {Messages().marginal(var)}")
+
+    def set_value(self, var_name, value_idx):
+        factor = self.factor_from_name('p(' + var_name + ')')
+        data = np.zeros(len(factor.data.array))
+        data[value_idx] = 1
+        factor.data = LabeledArray(data, [var_name])
+
+
+class Messages(object):
+    def __init__(self):
+        self.messages = {}
+
+    def _variable_to_factor_messages(self, variable, factor):
+        # print (f"_variable_to_factor_messages: {variable} to {factor}")        # Take the product over all incoming factors into this variable except the variable
+        incoming_messages = [
+            self.factor_to_variable_message(neighbor_factor, variable)
+            for neighbor_factor in variable.neighbors
+            if neighbor_factor.name != factor.name
+        ]
+
+        # If there are no incoming messages, this is 1
+        return np.prod(incoming_messages, axis=0)
+
+    def _factor_to_variable_messages(self, factor, variable):
+        # print (f"_factor_to_variable_message: {factor} to {variable}")
+        # Compute the product
+        factor_dist = np.copy(factor.data.array)
+        for neighbor_variable in factor.neighbors:
+            if neighbor_variable.name == variable.name:
+                continue
+            incoming_message = self.variable_to_factor_messages(
+                neighbor_variable, factor
+            )
+            factor_dist *= tile_to_other_dist_along_axis_name(
+                LabeledArray(incoming_message, [neighbor_variable.name]), factor.data
+            ).array
+        # Sum over the axes that aren't `variable`
+        other_axes = other_axes_from_labeled_axes(factor.data, variable.name)
+        return np.squeeze(np.sum(factor_dist, axis=other_axes))
+
+    def marginal(self, variable):
+        # p(variable) is proportional to the product of incoming messages to variable.
+        unnorm_p = np.prod(
+            [
+                self.factor_to_variable_message(neighbor_factor, variable)
+                for neighbor_factor in variable.neighbors
+            ],
+            axis=0,
+        )
+        # At this point, we can normalize this distribution
+        somme = np.sum(unnorm_p)
+        if somme == 0:
+            raise NoSolutionErrorInBP("marginals are nan")
+        return unnorm_p / somme
+
+    def variable_to_factor_messages(self, variable, factor):
+        # print (f"variable_to_factor_messages: {variable} to {factor}")
+        message_name = (variable.name, factor.name)
+        if message_name not in self.messages:
+            self.messages[message_name] = self._variable_to_factor_messages(
+                variable, factor
+            )
+        return self.messages[message_name]
+
+    def factor_to_variable_message(self, factor, variable):
+        # print (f"factor_to_variable_message: {factor} to {variable}")
+        message_name = (factor.name, variable.name)
+        if message_name not in self.messages:
+            self.messages[message_name] = self._factor_to_variable_messages(
+                factor, variable
+            )
+        return self.messages[message_name]
+
+
+def one_hot(size, index):
+    data = np.zeros(size, dtype=float)
+    data[index] = 1
+    return data

backend/vendor/ctor/continuator.py

@@ -0,0 +1,486 @@
+"""
+Copyright (c) 2025 Ynosound.
+All rights reserved.
+
+See LICENSE file in the project root for full license information.
+"""
+
+import pathlib
+import numpy as np
+import mido
+import random
+import time
+from difflib import SequenceMatcher
+import os
+
+from ctor.variable_order_markov import Variable_order_Markov
+from midi_stuff.mini_muse import Note
+
+"""
+- Split the music Continuator class from a generic Variable_Order_Markov, usable for any type of sequence (e.g. words).
+- Implementation of Continuator is different from original, to enable experiments with belief propagation and skips.
+- Representation of contexts of size 1 to K and their continuations with dictionaries. Trees/oracles are useless here.
+- Contexts are tuples of viewpoints AND continuations are viewpoints (see get_viewpoint()) (Unlike in the original)
+- Realizations are kept separately for each vp and reused during sampling. They are represented as addresses, i.e. tuple (index_of_melody, index_in_melody)
+- Sampling attempts to avoid too long repetitions (a kind of max-order) by avoiding singletons when it can
+- Sampling is performed both by belief propagation (1st order) and by variable-order and combined
+- Realization of viewpoints is performed with dynamic programming, à la HMM
+- Representation of polyphony is different from original Continuator. Clusters are not considered, only notes.
+They have a "status" describing how they were played originally, which is preserved at sampling. This enables more creativity for chords.
+- TODO: retrain periodically with computed viewpoints (bin quartiles for durations and velocity)
+- TODO: audio synthesis with Dawdreamer
+- TODO: add database storage of real time performances
+- TODO: data augmentation with inversions, negative harmony, etc.
+- TODO: rhythm transfer for data augmentation/control
+- TODO: server with js client, or huggingface solution or github page with python2js
+- TODO: use fine-tuning of transformers
+"""
+
+class Continuator2:
+
+    def __init__(self, midi_file: object = None, kmax: int = 4, transposition: bool = False) -> None:
+        self.learn_input = True
+        # self.vom = Variable_order_Markov(None, self.get_viewpoint, kmax)
+        self.vom = Variable_order_Markov(
+            sequence_of_stuff=None,
+            vp_lambda=self.get_viewpoint,  # identity viewpoint
+            kmax=kmax,
+            decay_fast_half_life=10,  # forget half the influence every ~10 events
+            decay_slow_half_life=80,  # for 'middle' band if you test it later
+            seed=0
+        )
+        # self.vom.set_period_mode("late")  # 'late' uses recent (fast-decayed) counts
+
+        self.tempo_msgs = []
+        self.transpose = transposition
+        self.forget_past = False
+        self.keep_last_n_melodies = 20
+        # for generation from midifiles
+        self.generate_length = 10
+        if midi_file is not None:
+            self.learn_file(midi_file, transposition)
+
+    @staticmethod
+    def get_viewpoint(note):
+        nb_beats_per_bin = 1
+        vp = tuple([note.pitch, int(note.duration / nb_beats_per_bin), note.overlaps_left(), note.overlaps_right()])
+        # vp = tuple([note.pitch, (int)(note.duration / 10)])
+        return vp
+
+    def set_learn_input(self, value):
+        self.learn_input = value
+
+    def get_learn_input(self):
+        return self.learn_input
+
+    def set_forget(self, forget_past):
+        self.forget_past = forget_past
+
+    def set_keep_last(self, keep):
+        self.keep_last_n_melodies = keep
+
+    def set_transpose(self, trans):
+        self.transpose = trans
+
+    def set_decay_mode(self, choice):
+        self.vom.set_period_mode(choice)
+
+    def get_phrase_titles(self):
+        return [f"{i + 1} phrase with {len(phrase)} notes" for i, phrase in enumerate(self.vom.input_sequences)]
+
+    def get_phrase(self, index):
+        return self.vom.input_sequences[index]
+
+    def clear_memory(self):
+        self.vom.clear_memory()
+
+    def clear_first_n_phrases(self, n):
+        self.vom.clear_first_N_phrases(n)
+
+    def clear_last_phrase(self):
+        self.vom.clear_last_phrase()
+
+    def learn_file(self, midi_file, transposition):
+        notes_original = self.extract_notes(midi_file)
+        self.learn_phrase(notes_original, transposition)
+
+    def learn_folder(self, folder_path, transpose=False):
+        all_files = []
+        for root, _, files in os.walk(folder_path):
+            for fname in files:
+                if fname.lower().endswith((".mid", ".midi")):
+                    full_path = os.path.join(root, fname)
+                    all_files.append(full_path)
+                    self.learn_file(full_path, transpose)
+        return all_files
+
+
+    def quantile_bins(self, values, N):
+        """
+        Compute bin edges that split the input values into N bins
+        with approximately equal number of points (quantiles).
+
+        Args:
+            values: list or array of numerical values (e.g., durations or velocities)
+            N: number of desired bins
+
+        Returns:
+            bin_edges: list of N+1 edges that define the bin intervals
+        """
+        values = np.array(values)
+        quantiles = np.linspace(0, 1, N + 1)
+        bin_edges = np.quantile(values, quantiles)
+        return bin_edges.tolist()
+
+
+    def get_all_input_durations(self):
+        all_durations = []
+        for note_seq in self.vom.input_sequences:
+            all_durations = all_durations + [n.duration for n in note_seq]
+        return all_durations
+
+    def compute_viewpoints(self, note_sequence):
+        all_durations = self.get_all_input_durations()
+        all_durations = all_durations + [n.duration for n in note_sequence]
+        all_durations.sort()
+        # print(self.vom.all_unique_viewpoints)
+        # print(self.quantile_bins(all_durations, 2))
+
+    def learn_phrase(self, note_sequence, transposition):
+        # should I forget some phrases ?
+        self.compute_viewpoints(note_sequence)
+        if len(note_sequence) == 0:
+            return
+        if self.forget_past and self.keep_last_n_melodies <= len(self.vom.input_sequences):
+            self.clear_first_n_phrases(1 + len(self.vom.input_sequences) - self.keep_last_n_melodies)
+        # all_pitches = [note.pitch for note in note_sequence]
+        # print(f"number of different pitches in train: {len(Counter(all_pitches))}")
+        # print(f"min pitch: {min(all_pitches)}, max pitch: {max(all_pitches)}")
+        # learns, possibly in 12 transpositions
+        trange = range(0, 1)
+        if transposition:
+            trange = range(-6, 6, 1)
+        for t in trange:
+            transposed = self.transpose_notes(note_sequence, t)
+            # learns one more sequence
+            self.vom.learn_sequence(transposed)
+
+
+    def learn_files(self, files, transposition=False):
+        # suppose at least one file has been learned already
+        for file in files:
+            self.learn_file(file, transposition)
+
+    # mido gives time in milliseconds from real input. Converts it into beast, assuming 120bpm
+    def learn_phrase_from_mido(self, phrase):
+        self.learn_phrase(self.get_phrase_from_mido(phrase), False)
+
+    def get_phrase_from_mido(self, phrase):
+        sequence = []
+        pending_notes = {}
+        # assign ABSOLUTE TIME to each message first, by cumulating all the deltas
+        # time here is in milliseconds
+        start_time = 0
+        for msg in phrase:
+            start_time = start_time + msg.time
+            msg.time = start_time
+        # joins note on and note off
+        for msg in phrase:
+            if msg.type == "note_on" and msg.velocity > 0:
+                pending_notes[msg.note] = msg
+            else:
+                if msg.type == "note_off" or (msg.type == 'note_on' and msg.velocity == 0):
+                    if msg.note not in pending_notes:
+                        print('⚠️ problem: note off does not match previous note on: ' + str(msg.note))
+                    else:
+                        note_on_msg = pending_notes[msg.note]
+                        start_time = note_on_msg.time * 2  # seconds to beat at 120 bpm
+                        duration = (msg.time - note_on_msg.time) * 2
+                        new_note = Note(note_on_msg.note, note_on_msg.velocity, duration, start_time)
+                        sequence.append(new_note)
+        self.set_delta_notes(sequence)
+        return sequence
+
+    @staticmethod
+    def transpose_notes(notes, t):
+        return [n.transpose(t) for n in notes]
+
+    def get_input_note(self, note_address):
+        # note_address is a tuple (melody index, index in melody)
+        return self.vom.get_input_object(note_address)
+
+    def is_starting_address(self, note_address):
+        return self.vom.is_starting_address(note_address)
+
+    def is_ending_address(self, note_address):
+        return self.vom.is_ending_address(note_address)
+
+    def get_start_vp(self):
+        return self.vom.start_padding
+
+    def get_end_vp(self):
+        return self.vom.end_padding
+
+    # @ time in midifile is expressed in ticks with some resolution. We convert it into beats, assuming 120bpm
+    def extract_notes(self, midi_file):
+        """Extracts the sequence of note-on events from a MIDI file."""
+        mid = mido.MidiFile(midi_file)
+        resolution = mid.ticks_per_beat
+        notes = []
+        pending_notes = np.empty(128, dtype=object)
+        pending_start_times = np.zeros(128)
+        current_time = 0
+        for track in mid.tracks:
+            for msg in track:
+                current_time += 2 * mido.tick2second(msg.time, ticks_per_beat=resolution, tempo=500000)  # in beats
+                if msg.type == 'set_tempo':
+                    self.tempo_msgs.append(msg.tempo)
+                if msg.type == "note_on" and msg.velocity > 0:
+                    new_note = Note(msg.note, msg.velocity, 0)
+                    notes.append(new_note)  # Store MIDI note number
+                    pending_notes[msg.note] = new_note
+                    pending_start_times[msg.note] = current_time
+                    new_note.set_start_time(current_time)
+                    new_note.set_duration(1)  # beat
+                if msg.type == "note_off" or (msg.type == "note_on" and msg.velocity == 0):
+                    if pending_notes[msg.note] is None:
+                        print("found 0 velocity note, skipping it")
+                        continue
+                    pending_note = pending_notes[msg.note]
+                    duration = current_time - pending_start_times[msg.note]
+                    pending_note.set_duration(duration)
+                    pending_notes[msg.note] = None
+                    pending_start_times[msg.note] = 0
+        # sets the note status w/r their neighbors
+        self.set_delta_notes(notes)
+        return np.array(notes)
+
+    @staticmethod
+    def set_delta_notes(notes):
+        for i, note in enumerate(notes):
+            if i > 0:
+                note.preceding_start_delta = note.start_time - notes[i - 1].start_time
+                note.preceding_end_delta = note.start_time - notes[i - 1].get_end_time()
+            if i < len(notes) - 1:
+                note.next_start_delta = notes[i + 1].start_time - note.get_end_time()
+                note.next_end_delta = notes[i + 1].get_end_time() - note.get_end_time()
+
+    @staticmethod
+    def all_midi_files_from_path(path_string):
+        path = pathlib.Path(path_string)
+        return list(path.glob('*.mid')) + list(path.glob('*.midi'))
+
+    def sample_sequence(self, prefix = None, length=50, constraints=None):
+        """
+        :param length:
+        :type constraints: dict
+        """
+        return self.vom.sample_sequence(length, prefix = prefix, constraints=constraints)
+
+    def sample_sequence_0(self, length=50, constraints=None):
+        """
+        :param length:
+        :type constraints: dict
+        """
+        return self.vom.sample_zero_order(length, constraints=constraints)
+
+    def realize_vp_sequence(self, vp_seq):
+        # print(f"realize sequence of {len(vp_seq)} viewpoints")
+        note_sequence = []
+        for i, vp in enumerate(vp_seq):
+            if i == 0:
+                initials = [real for real in self.vom.viewpoints_realizations[vp] if self.is_starting_address(real)]
+                if len(initials) != 0:
+                    note_sequence.append(random.choice(initials))
+                    continue
+            if i == len(vp_seq) - 1 and vp_seq[-1] == self.vom.end_padding:
+                lasts = [real for real in self.vom.viewpoints_realizations[vp] if self.is_ending_address(real)]
+                if len(lasts) != 0:
+                    note_sequence.append(random.choice(lasts))
+                    continue
+            note_sequence.append(random.choice(self.vom.viewpoints_realizations[vp]))
+
+        # domains = [self.viewpoints_realizations[vp] for vp in vp_seq]
+        # # # try to put together notes with compatible status @TODO
+        # unary_cost = lambda i, real: 0
+        # binary_cost = lambda i, real1, j, real2: (int)(not self.get_input_note(real1).is_compatible_with(self.get_input_note(real2)))
+        # optimizer = VariableDomainSequenceOptimizer(domains, unary_cost, binary_cost)
+        # cost, best_seq = optimizer.fit()
+
+        result = self.set_timing(note_sequence)
+        return result
+        # return best_seq
+
+    def get_vp_for_pitch(self, pitch):
+        # this is way too costly, but used only at constraint initialization. Can be cached
+        vps = []
+        for vp, notes in self.vom.viewpoints_realizations.items():
+            for note_address in notes:
+                note = self.vom.get_input_object(note_address)
+                if note.pitch == pitch:
+                    vps.append(vp)
+        return random.choice(vps)
+
+    def set_timing(self, idx_sequence):
+        sequence = []
+        start_time = 0
+        for i, note_address in enumerate(idx_sequence):
+            note_copy = self.get_input_note(note_address).copy()
+            # keeps the inter note time to be the same as in the original sequence
+            if len(sequence) > 0:
+                preceding = sequence[-1]
+                preceding_address = idx_sequence[i - 1]
+                delta = self.decide_delta_time(note_address, note_copy, preceding_address, preceding)
+                start_time += delta
+            note_copy.set_start_time(start_time)
+            sequence.append(note_copy)
+        # shift the whole sequence to t=0
+        first_note_time = sequence[0].start_time
+        for note in sequence:
+            note.start_time = note.start_time - first_note_time
+        return sequence
+
+    @staticmethod
+    def get_pitch_string(note_sequence):
+        return "".join([str(note.pitch) + " " for note in note_sequence])
+
+    @staticmethod
+    def decide_delta_time(note_to_add_address, note_to_add, current_address, current_note):
+        if current_note is None:
+            return 0
+        cur_status = current_note.get_status_right()
+        note_to_add_status = note_to_add.get_status_left()
+        delta = current_note.duration + current_note.next_start_delta
+        if cur_status == "inside":
+            if note_to_add_status == "before":
+                return delta
+            if note_to_add_status == "overlaps":
+                return delta
+            if note_to_add_status == "contains":
+                return delta
+        if cur_status == "overlaps":
+            if note_to_add_status == "before":
+                return delta
+            if note_to_add_status == "overlaps":
+                return delta
+            if note_to_add_status == "contains":
+                return delta
+        if cur_status == "after":
+            if note_to_add_status == "before":
+                return delta
+            if note_to_add_status == "overlaps":
+                return delta
+            if note_to_add_status == "contains":
+                return delta
+        print("should not be here")
+        return 0
+
+    def save_midi(self, sequence, output_file, tempo=120, sustain=False):
+        ms = self.create_mido_sequence(sequence, tempo=tempo, sustain=sustain)
+        ms.save(output_file)
+
+    def create_mido_sequence(self, sequence, tempo=120, sustain=False):
+        mid = mido.MidiFile()
+        track = mido.MidiTrack()
+        mid.tracks.append(track)
+        # create a new sequence with the right start_times
+        # create all mido messages and sort them
+        mido_sequence = []
+        for note in sequence:
+            try:
+                mido_sequence.append(
+                    mido.Message(
+                        "note_on",
+                        note=note.pitch,
+                        velocity=note.velocity,
+                        time=note.start_time,
+                    )
+                )
+            except:
+                print("Something went wrong")
+            mido_sequence.append(
+                mido.Message(
+                    "note_off",
+                    note=note.pitch,
+                    velocity=0,
+                    time=note.start_time + note.duration,
+                )
+            )
+        mido_sequence.sort(key=lambda messg: messg.time)
+        if sustain:
+            # add pedal message
+            mido_sequence.insert(0, mido.Message(
+                "control_change",
+                control=64,
+                value=127,
+                time=0,
+            ))
+        if tempo == -1 and len(self.tempo_msgs) > 0:
+            # takes the original average tempo
+            average_tempo = int(np.sum(self.tempo_msgs) / len(self.tempo_msgs))
+            mido_sequence.insert(0, mido.MetaMessage(type='set_tempo', tempo=average_tempo))
+        current_time = 0
+        # converts beats into ticks, assuming 480 ticks per second
+        for msg in mido_sequence:
+            delta_in_beats = msg.time - current_time
+            delta_in_ticks = int(mid.ticks_per_beat * delta_in_beats)
+            msg.time = delta_in_ticks
+            track.append(msg)
+            current_time += delta_in_beats
+        return mid
+
+    def get_longest_subsequence_with_train(self, address_sequence):
+        note_sequence = [self.get_input_note(address) for address in address_sequence]
+        sequence_string = self.get_pitch_string(note_sequence)
+        best = 0
+        for input_seq in self.vom.input_sequences:
+            train_string = self.get_pitch_string(input_seq)
+            match = SequenceMatcher(
+                None, train_string, sequence_string, autojunk=False
+            ).find_longest_match()
+            nb_notes_common = train_string[match.a: match.a + match.size].count(" ")
+            if nb_notes_common > best:
+                best = nb_notes_common
+        return best
+
+
+
+if __name__ == '__main__':
+    # midi_file_path = "../../data/Ravel_jeaux_deau.mid"
+    # midi_file_path = "../../data/test_sequence_3notes.mid"
+    # midi_file_path = "../../data/test_sequence_arpeggios.mid"
+    # midi_file_path = "../../data/debussy_prelude.mid"
+    # midi_file_path = "../../data/prelude_c_expressive.mid"
+    # midi_file_path = "../../data/prelude_c_linear.mid"
+    # midi_file_path = "../../data/partita_piano_1/pr1_1_joined.mid"
+    # midi_file_path = "../../data/take6/A_quiet_place_joined.mid"
+    # midi_file_path = "../../data/prelude_c_expressive.mid"
+    midi_file_path = "../data/prelude_c.mid"
+    # midi_file_path = "../../data/bach_partita_mono.midi"
+    # midi_file_path = "../../data/keith/train/K7_MD.mid"
+    # midi_file_path = "../../../maestro-v3.0.0/2004/MIDI-Unprocessed_SMF_12_01_2004_01-05_ORIG_MID--AUDIO_12_R1_2004_03_Track03_wav--1.midi"
+    t0 = time.perf_counter_ns()
+    generator = Continuator2(midi_file_path, 4, transposition=False)
+    # matrix = generator.get_first_order_matrix()
+    # print(matrix.shape)
+    # t1 = time.perf_counter_ns()
+    # print(f"total time: {(t1 - t0) / 1000000}")
+    # Sampling a new sequence from the  model
+    constraints = {0: generator.get_vp_for_pitch(62), 19: generator.get_end_vp()}
+    # constraints[0] = generator.get_start_vp()
+    generated_sequence = generator.sample_sequence(length=20, constraints=constraints)
+    t1 = time.perf_counter_ns()
+    print(f"total time: {(t1 - t0) / 1_000_000}ms")
+    # print(f"generated sequence of length {len(generated_sequence)}")
+    sequence_to_render = generated_sequence[0:-1]
+    rendered_sequence = generator.realize_vp_sequence(sequence_to_render)
+    generator.save_midi(rendered_sequence, "../data/ctor2_output.mid", tempo=-1, sustain=False)
+    # pmpr = generator.create_pr®etty_midi_pr(generated_sequence)
+    # generator.plot_piano_roll(pmpr)
+    # os.system("say sequence generated &")
+    # print("Generated Sequence:", generated_sequence)
+    # print("computing plagiarism:")
+    # print(
+    #     f"{generator.get_longest_subsequence_with_train(generated_sequence)} successive notes in commun with train"
+    # )
+    generator.vom.show_conts_structure()

backend/vendor/ctor/dynaprog.py

@@ -0,0 +1,184 @@
+"""
+Copyright (c) 2025 Ynosound.
+All rights reserved.
+
+See LICENSE file in the project root for full license information.
+"""
+
+import numpy as np
+
+
+class VariableDomainSequenceOptimizer:
+    """
+    A class for solving sequence assignment problems with variable domains:
+
+    We have positions i = 0..n-1, each with its own domain[i].
+    We want to minimize:
+        sum_{i=0}^{n-1} unary_cost(i, x_i)
+      + sum_{i=0}^{n-2} binary_cost(i, x_i, i+1, x_{i+1})
+
+    using dynamic programming, supporting different domain sizes per position.
+    """
+
+    def __init__(self, domains, unary_cost, binary_cost):
+        """
+        Parameters
+        ----------
+        domains : list of lists
+            domains[i] is the list of allowable labels for position i.
+            E.g., domains[0] = [0,1,2], domains[1] = ['A','B'], etc.
+        unary_cost : function (i, x) -> float
+            A function that gives the cost of assigning value x at position i.
+        binary_cost : function (i, x, i+1, y) -> float
+            A function that gives the cost of assigning x at position i and y at position i+1.
+        """
+        # n is the total number of positions
+        self.n = len(domains)
+        # domains[i] is a list of valid labels for position i
+        self.domains = domains
+        # cost functions
+        self.unary_cost_func = unary_cost
+        self.binary_cost_func = binary_cost
+
+        # Precompute unary arrays: U[i], shape (|D_i|,)
+        self.U = self._compute_unary_arrays()
+
+        # Precompute binary arrays: B[i], shape (|D_i|, |D_{i+1}|)
+        if self.n > 1:
+            self.B = self._compute_binary_arrays()
+        else:
+            self.B = []  # no binary cost if only one position
+
+        # DP tables (filled by fit)
+        # dp[i] will be shape (|D_i|,)
+        # backpointer[i] will be shape (|D_i|,) storing the chosen index in domain[i+1]
+        self.dp = [None] * self.n
+        self.backpointer = [None] * self.n
+
+    def _compute_unary_arrays(self):
+        """
+        For each position i, create a 1D array of shape (|D_i|,)
+        where U[i][d] = unary_cost_func(i, domains[i][d]).
+        """
+        U = []
+        for i in range(self.n):
+            dom_i = self.domains[i]
+            arr = np.zeros(len(dom_i), dtype=np.float64)
+            for d, label in enumerate(dom_i):
+                arr[d] = self.unary_cost_func(i, label)
+            U.append(arr)
+        return U
+
+    def _compute_binary_arrays(self):
+        """
+        For each i in [0..n-2], create a 2D array B[i] of shape (|D_i|, |D_{i+1}|)
+        where B[i][d1, d2] = binary_cost_func(i, domains[i][d1], i+1, domains[i+1][d2]).
+        """
+        B = []
+        for i in range(self.n - 1):
+            dom_i = self.domains[i]
+            dom_next = self.domains[i + 1]
+            mat = np.zeros((len(dom_i), len(dom_next)), dtype=np.float64)
+            for d1, label1 in enumerate(dom_i):
+                for d2, label2 in enumerate(dom_next):
+                    mat[d1, d2] = self.binary_cost_func(i, label1, i + 1, label2)
+            B.append(mat)
+        return B
+
+    def fit(self):
+        """
+        Run the dynamic programming to find the minimum total cost and the best assignment.
+
+        Returns
+        -------
+        (min_cost, best_sequence)
+          min_cost : float
+              The minimal total cost.
+          best_sequence : list
+              A list of length n with the optimal label for each position.
+        """
+        # If n == 0, trivial
+        if self.n == 0:
+            return 0.0, []
+
+        # dp[i], shape (|D_i|,) -> minimal cost from position i onward if x_i = domain[i][d]
+        # backpointer[i], shape (|D_i|,) -> best index in domain[i+1] for each d in domain[i].
+
+        # Base case: i = n-1
+        self.dp[self.n - 1] = self.U[self.n - 1].copy()
+        self.backpointer[self.n - 1] = np.full(len(self.domains[self.n - 1]), -1, dtype=np.int64)
+
+        # Fill backward from i = n-2 down to 0
+        for i in range(self.n - 2, -1, -1):
+            dom_i_size = len(self.domains[i])
+            dom_next_size = len(self.domains[i + 1])
+
+            dp_i = np.zeros(dom_i_size, dtype=np.float64)
+            bp_i = np.zeros(dom_i_size, dtype=np.int64)
+
+            # cost_matrix = B[i] + dp[i+1]
+            # B[i] is shape (dom_i_size, dom_next_size)
+            # dp[i+1] is shape (dom_next_size,)
+            # so cost_matrix is shape (dom_i_size, dom_next_size), where
+            # cost_matrix[d1, d2] = B[i][d1, d2] + dp[i+1][d2]
+            cost_matrix = self.B[i] + self.dp[i + 1]
+
+            # For each d1 in [0..dom_i_size-1], we find the minimal cost over d2
+            # min_costs[d1] = min_{d2} [ cost_matrix[d1, d2] ]
+            # best_next[d1] = argmin_{d2} [ cost_matrix[d1, d2] ]
+            min_costs = np.min(cost_matrix, axis=1)
+            best_next = np.argmin(cost_matrix, axis=1)
+
+            dp_i[:] = self.U[i] + min_costs
+            bp_i[:] = best_next
+
+            self.dp[i] = dp_i
+            self.backpointer[i] = bp_i
+
+        # Find the best start label at i=0
+        min_cost = np.min(self.dp[0])
+        best_start = np.argmin(self.dp[0])
+
+        # Reconstruct solution
+        best_sequence = [None] * self.n
+        best_sequence[0] = self.domains[0][best_start]
+
+        prev_index = best_start
+        for i in range(0, self.n - 1):
+            next_index = self.backpointer[i][prev_index]
+            best_sequence[i + 1] = self.domains[i + 1][next_index]
+            prev_index = next_index
+
+        return min_cost, best_sequence
+
+
+# ---------------------------------------------------------------------------
+# Example usage:
+if __name__ == "__main__":
+    # Suppose we have 4 positions, each with a different domain of labels:
+    domains = [
+        [0, 1],  # position 0
+        [0, 1, 2],  # position 1
+        ['A', 'B'],  # position 2
+        [10, 20, 30]  # position 3
+    ]
+
+
+    # A simple unary cost function that depends on i and x
+    def unary_cost(i, x):
+        # e.g., cost is i * int(x != 0) just as a silly example
+        # for non-integer x, we'll treat 'A'/'B' or whatever carefully
+        return 1.0 if x != 0 else 0.0
+
+
+    # A simple binary cost function
+    def binary_cost(i, x, j, y):
+        # For demonstration, let's say cost = 1 if x == y, else 0
+        return float(x == y)
+
+
+    optimizer = VariableDomainSequenceOptimizer(domains, unary_cost, binary_cost)
+    cost, best_seq = optimizer.fit()
+
+    print("Minimal cost:", cost)
+    print("Best sequence:", best_seq)

backend/vendor/ctor/markov_analysis.py

@@ -0,0 +1,159 @@
+# markov_ergodicity.py
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+import numpy as np
+import math
+
+@dataclass
+class MarkovAnalysis:
+    n_states: int
+    irreducible: bool
+    period: Optional[int]
+    aperiodic: bool
+    ergodic: bool
+    stationary_distribution: np.ndarray
+    sccs: List[List[int]]
+    primitive_k: Optional[int]
+
+def _validate_row_stochastic(P: np.ndarray, tol: float) -> None:
+    if P.ndim != 2 or P.shape[0] != P.shape[1]:
+        raise ValueError("P must be a square matrix.")
+    if (P < -tol).any():
+        raise ValueError("P must have nonnegative entries (within tolerance).")
+    row_sums = P.sum(axis=1)
+    if not np.allclose(row_sums, 1.0, atol=1e-9):
+        raise ValueError("Each row of P must sum to 1 (within tolerance).")
+
+def _adjacency(P: np.ndarray, tol: float) -> Tuple[List[List[int]], List[List[int]]]:
+    n = P.shape[0]
+    adj = [[] for _ in range(n)]
+    radj = [[] for _ in range(n)]
+    for i in range(n):
+        for j in range(n):
+            if P[i, j] > tol:
+                adj[i].append(j)
+                radj[j].append(i)
+    return adj, radj
+
+def _kosaraju_scc(adj: List[List[int]], radj: List[List[int]]) -> Tuple[List[List[int]], List[int]]:
+    n = len(adj)
+    visited = [False] * n
+    order: List[int] = []
+
+    def dfs1(u: int):
+        stack = [u]
+        while stack:
+            v = stack.pop()
+            if v < 0:
+                order.append(~v)
+                continue
+            if visited[v]:
+                continue
+            visited[v] = True
+            stack.append(~v)
+            for w in adj[v]:
+                if not visited[w]:
+                    stack.append(w)
+
+    for v in range(n):
+        if not visited[v]:
+            dfs1(v)
+
+    comp = [-1] * n
+    cid = 0
+    for v in reversed(order):
+        if comp[v] != -1:
+            continue
+        stack = [v]
+        comp[v] = cid
+        while stack:
+            x = stack.pop()
+            for w in radj[x]:
+                if comp[w] == -1:
+                    comp[w] = cid
+                    stack.append(w)
+        cid += 1
+
+    sccs: List[List[int]] = [[] for _ in range(cid)]
+    for v in range(n):
+        sccs[comp[v]].append(v)
+    return sccs, comp
+
+def _is_irreducible(P: np.ndarray, tol: float) -> Tuple[bool, List[List[int]], List[int], List[List[int]]]:
+    adj, radj = _adjacency(P, tol)
+    sccs, comp = _kosaraju_scc(adj, radj)
+    return (len(sccs) == 1), sccs, comp, adj
+
+def _period_of_irreducible(adj: List[List[int]]) -> int:
+    n = len(adj)
+    dist = [-1] * n
+    g = 0
+    dist[0] = 0
+    stack = [0]
+    while stack:
+        u = stack.pop()
+        for v in adj[u]:
+            if dist[v] == -1:
+                dist[v] = dist[u] + 1
+                stack.append(v)
+            else:
+                g = math.gcd(g, abs(dist[u] + 1 - dist[v]))
+    return max(1, g)
+
+def _stationary_distribution(P: np.ndarray, tol: float) -> np.ndarray:
+    n = P.shape[0]
+    A = np.eye(n) - P.T
+    A[-1, :] = 1.0
+    b = np.zeros(n); b[-1] = 1.0
+    pi, *_ = np.linalg.lstsq(A, b, rcond=None)
+    pi = np.maximum(pi, 0.0)
+    s = pi.sum()
+    if s <= tol:
+        w, v = np.linalg.eig(P.T)
+        i = int(np.argmin(np.abs(w - 1.0)))
+        pi = np.real(v[:, i])
+        pi = np.maximum(pi, 0.0)
+        s = pi.sum()
+        if s <= tol:
+            raise ValueError("Could not compute a valid stationary distribution.")
+    return pi / pi.sum()
+
+def _primitive_k(P: np.ndarray, tol: float, max_k: int) -> Optional[int]:
+    n = P.shape[0]
+    M = P.copy()
+    for k in range(1, max_k + 1):
+        if (M > tol).all():
+            return k
+        M = M @ P
+    return None
+
+def analyze_markov_chain(
+    P: np.ndarray,
+    tol: float = 1e-12,
+    compute_primitive: bool = False,
+    max_k: int = 256,
+) -> MarkovAnalysis:
+    P = np.asarray(P, dtype=float)
+    _validate_row_stochastic(P, tol)
+    irreducible, sccs, comp, adj = _is_irreducible(P, tol)
+    if irreducible:
+        period = _period_of_irreducible(adj)
+        aperiodic = (period == 1)
+        ergodic = aperiodic
+    else:
+        period = None
+        aperiodic = False
+        ergodic = False
+    pi = _stationary_distribution(P, tol)
+    prim_k = _primitive_k(P, tol, max_k) if compute_primitive else None
+    return MarkovAnalysis(
+        n_states=P.shape[0],
+        irreducible=irreducible,
+        period=period,
+        aperiodic=aperiodic,
+        ergodic=ergodic,
+        stationary_distribution=pi,
+        sccs=sccs,
+        primitive_k=prim_k,
+    )

backend/vendor/ctor/variable_order_markov.py

@@ -0,0 +1,828 @@
+"""
+Copyright (c) 2025 Ynosound.
+All rights reserved.
+
+See LICENSE file in the project root for full license information.
+"""
+
+from collections import Counter, defaultdict
+from typing import Dict, Tuple, Optional
+
+import numpy as np
+import random
+from difflib import SequenceMatcher
+
+from ctor.belief_propag import PGM, LabeledArray, Messages, NoSolutionErrorInBP
+from ctor.markov_analysis import analyze_markov_chain
+
+
+# -----------------------------------------------------------------------------
+# Time-decay building blocks
+# -----------------------------------------------------------------------------
+
+class LazyExpCounter:
+    """
+    Per-key lazy exponential counter (exact).
+    Stores (weight, last_update_step) for each key and applies decay d**Δ on read or update.
+
+    data: key(int) -> (weight: float, last_step: int)
+    """
+    __slots__ = ("decay", "data", "eps")
+
+    def __init__(self, decay: float, eps: float = 1e-12):
+        self.decay = float(decay)   # in (0,1], 1.0 = no decay
+        self.data: Dict[int, Tuple[float, int]] = {}
+        self.eps = eps
+
+    def update(self, key: int, step: int, incr: float = 1.0) -> None:
+        w, last = self.data.get(key, (0.0, step))
+        if w > 0.0 and step > last and self.decay < 1.0:
+            w *= self.decay ** (step - last)
+        w += incr
+        self.data[key] = (w, step)
+
+    def weights(self, now: int) -> Dict[int, float]:
+        if not self.data:
+            return {}
+        if self.decay >= 1.0:
+            # no decay, just return current weights
+            return {k: w for k, (w, _) in self.data.items() if w > self.eps}
+        d = self.decay
+        out: Dict[int, float] = {}
+        for k, (w, t) in self.data.items():
+            cw = w * (d ** (now - t))
+            if cw > self.eps:
+                out[k] = cw
+        return out
+
+
+class MultiCounter:
+    """
+    For each (context -> next) relation, maintain:
+      - full : exact counts (no decay)
+      - slow : lazy exponential counter (long half-life)
+      - fast : lazy exponential counter (short half-life)
+
+    Exposes 4 "views":
+      - 'full'   : full counts (no decay)
+      - 'late'   : fast (recent)
+      - 'middle' : slow - fast   (>=0)   -> band around intermediate ages
+      - 'early'  : full - slow   (>=0)   -> emphasize older
+    """
+    __slots__ = ("full", "slow", "fast", "track_decays")
+
+    def __init__(self, decay_fast: float, decay_slow: float):
+        self.full: Counter[int] = Counter()
+        self.track_decays = (decay_fast < 1.0) or (decay_slow < 1.0)
+        self.fast = LazyExpCounter(decay_fast) if self.track_decays else None
+        self.slow = LazyExpCounter(decay_slow) if self.track_decays else None
+
+    def update(self, nxt: int, step: int, incr: float = 1.0) -> None:
+        self.full[nxt] += incr
+        if self.track_decays:
+            self.fast.update(nxt, step, incr)
+            self.slow.update(nxt, step, incr)
+
+    def weights(self, now: int, mode: str = "full") -> Dict[int, float]:
+        if (mode == "full") or (not self.track_decays):
+            return {k: float(v) for k, v in self.full.items() if v > 0}
+
+        if mode == "late":
+            return self.fast.weights(now)
+
+        if mode == "middle":
+            f = self.fast.weights(now)
+            s = self.slow.weights(now)
+            keys = set(f) | set(s)
+            out: Dict[int, float] = {}
+            for k in keys:
+                v = s.get(k, 0.0) - f.get(k, 0.0)
+                if v > 0.0:
+                    out[k] = v
+            return out
+
+        if mode == "early":
+            s = self.slow.weights(now)
+            keys = set(self.full) | set(s)
+            out: Dict[int, float] = {}
+            for k in keys:
+                v = float(self.full.get(k, 0)) - s.get(k, 0.0)
+                if v > 0.0:
+                    out[k] = v
+            return out
+
+        raise ValueError(f"unknown mode '{mode}'")
+
+    def nonzero_options(self, now: int, mode: str) -> int:
+        return len(self.weights(now, mode))
+
+
+# -----------------------------------------------------------------------------
+# Sentinels
+# -----------------------------------------------------------------------------
+
+class _Start_vp:
+    def __init__(self):
+        pass
+
+
+class _End_vp:
+    def __init__(self):
+        pass
+
+
+# -----------------------------------------------------------------------------
+# Variable-order Markov with one unified continuation dictionary + MultiCounter
+# -----------------------------------------------------------------------------
+
+class Variable_order_Markov:
+    def __init__(
+        self,
+        sequence_of_stuff,
+        vp_lambda,
+        kmax: int = 5,
+        # optional half-lives (in events or seconds) to enable decay views
+        decay_fast_half_life: Optional[float] = None,
+        decay_slow_half_life: Optional[float] = None,
+        seed: Optional[int] = None,
+    ):
+        # inputs
+        self.viewpoint_lambda = vp_lambda
+        self.start_padding = _Start_vp()
+        self.end_padding = _End_vp()
+        self.kmax = int(kmax)
+        self.rng = random.Random(seed)
+
+        # half-life -> decay base d = 2^(-1/H); None/<=0 => d=1 (no decay)
+        def _decay_from_half_life(H: Optional[float]) -> float:
+            if not H or H <= 0:
+                return 1.0
+            return 2.0 ** (-1.0 / float(H))
+
+        self.decay_fast = _decay_from_half_life(decay_fast_half_life)
+        # if only fast given, slow defaults ~8x slower (heuristic)
+        self.decay_slow = _decay_from_half_life(
+            decay_slow_half_life if decay_slow_half_life
+            else (decay_fast_half_life * 8 if decay_fast_half_life else None)
+        )
+
+        # selectable "view" for reading transitions: 'full'|'late'|'middle'|'early'
+        self.period_mode: str = "full"
+
+        # global clock for lazy decay
+        self.global_step: int = 0
+        # if set, freeze decay at this step for reads
+        self.decay_freeze_at: Optional[int] = None
+
+        self.clear_memory()
+        if sequence_of_stuff is not None:
+            self.learn_sequence(sequence_of_stuff)
+
+    # ------------------ controls for views/decay ------------------
+
+    def set_period_mode(self, mode: str) -> None:
+        assert mode in ("full", "late", "middle", "early")
+        self.period_mode = mode
+        self.first_order_matrix = None  # force rebuild if necessary
+
+    def freeze_decay(self) -> None:
+        self.decay_freeze_at = self.global_step
+        self.first_order_matrix = None
+
+    def unfreeze_decay(self) -> None:
+        self.decay_freeze_at = None
+        self.first_order_matrix = None
+
+    # ------------------ memory / model ------------------
+
+    def _make_counter(self) -> MultiCounter:
+        return MultiCounter(self.decay_fast, self.decay_slow)
+
+    def clear_memory(self):
+        self.input_sequences = []
+        self.all_unique_viewpoints = []
+        self.vp2index = {}
+        self.viewpoints_realizations = defaultdict(list)
+
+        # ✅ ONE unified dictionary for all context lengths:
+        # key = context tuple (length = order), value = MultiCounter
+        self.ctx_to_continuations: Dict[Tuple[object, ...], MultiCounter] = defaultdict(self._make_counter)
+
+        self.first_order_matrix = None
+
+    def clear_first_N_phrases(self, n):
+        if not self.input_sequences:
+            print("nothing to remove, memory is empty")
+            return
+        if len(self.input_sequences) < n:
+            print("nothing to remove, memory is less than " + str(n))
+            return
+        sequences_to_learn = self.input_sequences[n:]
+        self.clear_memory()
+        for seq in sequences_to_learn:
+            self.learn_sequence(seq)
+
+    def clear_last_phrase(self):
+        if not self.input_sequences:
+            print("nothing to remove, memory is empty")
+            return
+        sequences_to_learn = self.input_sequences[:-1]
+        self.clear_memory()
+        for seq in sequences_to_learn:
+            self.learn_sequence(seq)
+
+    def learn_sequence(self, sequence_of_stuff):
+        self.first_order_matrix = None
+        self.input_sequences.append(sequence_of_stuff)
+        self.build_vo_markov_model(sequence_of_stuff)
+
+    def get_input_object(self, obj_address):
+        # note_address is a tuple (melody index, index in melody)
+        return self.input_sequences[obj_address[0]][obj_address[1]]
+
+    @staticmethod
+    def is_starting_address(note_address):
+        # 0 is the start_padding, 1 is the first actual item
+        return note_address[1] == 1
+
+    def is_ending_address(self, note_address):
+        return note_address[1] == len(self.input_sequences[note_address[0]]) - 2
+
+    def is_end_padding(self, vp):
+        return vp == self.end_padding
+
+    def voc_size(self):
+        return len(self.all_unique_viewpoints)
+
+    def random_initial_vp(self):
+        mc = self.ctx_to_continuations.get((self.start_padding,), None)
+        if not mc:
+            raise RuntimeError("Model has no start contexts yet.")
+        now = self.global_step if self.decay_freeze_at is None else self.decay_freeze_at
+        w = mc.weights(now, self.period_mode) or mc.weights(now, "full")
+        items, weights = zip(*w.items())
+        j = self.rng.choices(items, weights=weights, k=1)[0]
+        return self.all_unique_viewpoints[j]
+
+    def random_vp_with_probs(self, probs):
+        idx = np.random.choice(len(probs), p=probs)
+        return self.all_unique_viewpoints[idx]
+
+    def get_all_unique_viewpoints_except_paddings(self):
+        sp, ep = self.start_padding, self.end_padding
+        return [vp for vp in self.all_unique_viewpoints if vp not in (sp, ep)]
+
+    def index_of_vp(self, vp):
+        return self.vp2index[vp]
+
+    def build_vo_markov_model(self, real_sequence):
+        """Build/accumulate a VO-Markov model up to order kmax using one unified dict."""
+        vp_seq = [self.start_padding] + [self.get_viewpoint(obj) for obj in real_sequence] + [self.end_padding]
+
+        # register unique viewpoints
+        for vp in vp_seq:
+            if vp not in self.vp2index:
+                self.vp2index[vp] = len(self.all_unique_viewpoints)
+                self.all_unique_viewpoints.append(vp)
+
+        # realizations (keep your original addressing)
+        sequence_index = len(self.input_sequences) - 1
+        for i, vp in enumerate(vp_seq[1:-1]):
+            self.add_viewpoint_realization(i, sequence_index, vp)
+
+        # contexts update (single pass)
+        vp2idx = self.vp2index
+        n = len(vp_seq)
+        kmax_eff = min(self.kmax, n - 1)
+        for i in range(1, n):  # i is index of "next" token
+            nxt_idx = vp2idx[vp_seq[i]]
+            max_k = min(kmax_eff, i)  # context length up to kmax
+            for k in range(1, max_k + 1):
+                ctx = tuple(vp_seq[i - k:i])
+                self.ctx_to_continuations[ctx].update(nxt_idx, self.global_step)
+            # advance global time once per token
+            self.global_step += 1
+
+        # ensure end->end exists (so rows aren’t empty)
+        self.ctx_to_continuations[(self.end_padding,)].update(vp2idx[self.end_padding], self.global_step)
+        self.global_step += 1
+
+        self.first_order_matrix = None
+
+        # shows an analysis of the markov chain
+        # first_order = self.get_first_order_matrix_no_paddings()
+        # ma = analyze_markov_chain(first_order, tol=1e-12, compute_primitive=False, max_k=256)
+        # print(ma)
+
+
+    # ------------------ priors / zero-order ------------------
+
+    def get_priors(self):
+        key_counts = {key: len(continuations) for key, continuations in self.viewpoints_realizations.items()}
+        total_count = sum(key_counts.values())
+        priors = {key: count / total_count for key, count in key_counts.items()} if total_count > 0 else {}
+        sorted_keys = self.get_all_unique_viewpoints_except_paddings()
+        probability_vector = np.array([priors.get(key, 0.0) for key in sorted_keys], dtype=float)
+        return probability_vector
+
+    def sample_zero_order(self, k, constraints=None):
+        priors = self.get_priors()
+        return random.choices(self.get_all_unique_viewpoints_except_paddings(), weights=priors, k=k)
+
+    # ------------------ realizations ------------------
+
+    def add_viewpoint_realization_old(self, i, sequence_index, vp):
+        new_address = (sequence_index, i)
+        self.viewpoints_realizations[vp].append(new_address)
+
+    def add_viewpoint_realization_new(self, i, sequence_index, vp):
+        new_address = (sequence_index, i)
+        if self.is_starting_address(new_address) or self.is_ending_address(new_address):
+            self.viewpoints_realizations[vp].append(new_address)
+            return
+        new_note = self.get_input_object(new_address)
+        for real in self.viewpoints_realizations[vp]:
+            real_note = self.get_input_object(real)
+            if real_note.is_similar_realization(new_note):
+                return
+        self.viewpoints_realizations[vp].append(new_address)
+
+    add_viewpoint_realization = add_viewpoint_realization_old
+
+    # ------------------ matrices ------------------
+
+    def get_first_order_matrix_old(self):
+        """
+        Legacy-style matrix from FULL counts on order-1 contexts, using the unified dictionary.
+        """
+        keys = self.all_unique_viewpoints
+        n = len(keys)
+        result = np.zeros((n, n), dtype=float)
+        now = self.global_step if self.decay_freeze_at is None else self.decay_freeze_at
+        for i_vp, vp in enumerate(keys):
+            mc = self.ctx_to_continuations.get((vp,), None)
+            if not mc:
+                continue
+            row_counts = mc.weights(now, "full")
+            for j, c in row_counts.items():
+                result[i_vp, j] = c
+            s = result[i_vp].sum()
+            if s > 0:
+                result[i_vp] /= s
+        return result
+
+    def get_first_order_matrix(self):
+        """
+        Build the order-1 transition matrix P[i, j] with the current period_mode.
+        Caches only in 'full' mode (time-invariant). Decayed/band views depend on 'now'.
+        """
+        if self.first_order_matrix is not None and self.period_mode == "full":
+            return self.first_order_matrix
+
+        keys = self.all_unique_viewpoints
+        n = len(keys)
+        counts = np.zeros((n, n), dtype=float)
+        now = self.global_step if self.decay_freeze_at is None else self.decay_freeze_at
+
+        for i, vp in enumerate(keys):
+            mc = self.ctx_to_continuations.get((vp,), None)
+            if not mc:
+                continue
+            w = mc.weights(now, self.period_mode)
+            if not w:
+                continue
+            row = counts[i]
+            for j, c in w.items():
+                row[j] = float(c)
+
+        # Normalize rows
+        row_sums = counts.sum(axis=1, keepdims=True)
+        result = np.zeros_like(counts)
+        np.divide(counts, row_sums, out=result, where=row_sums > 0)
+
+        self.first_order_matrix = result if self.period_mode == "full" else None
+        # ma = analyze_markov_chain(result, tol=1e-12, compute_primitive=False, max_k=256)
+        # print(ma)
+        return result
+
+    def get_first_order_matrix_no_paddings(self):
+        """
+        Build the order-1 transition matrix P[i, j] with the current period_mode.
+        Caches only in 'full' mode (time-invariant). Decayed/band views depend on 'now'.
+        """
+
+        keys = self.get_all_unique_viewpoints_except_paddings()
+        n = len(keys)
+        counts = np.zeros((n, n), dtype=float)
+        now = self.global_step if self.decay_freeze_at is None else self.decay_freeze_at
+
+        for i, vp in enumerate(keys):
+            mc = self.ctx_to_continuations.get((vp,), None)
+            if not mc:
+                continue
+            w = mc.weights(now, self.period_mode)
+            if not w:
+                continue
+            row = counts[i]
+            for j, c in w.items():
+                # if j > n, it means it is a start or end vp, so should skip
+                if j < n:
+                    row[j] = float(c)
+
+        # Normalize rows
+        row_sums = counts.sum(axis=1, keepdims=True)
+        result = np.zeros_like(counts)
+        np.divide(counts, row_sums, out=result, where=row_sums > 0)
+        return result
+
+    # ------------------ viewpoints & sampling ------------------
+
+    def get_viewpoint(self, real_object):
+        if self.viewpoint_lambda is None:
+            return real_object
+        return self.viewpoint_lambda(real_object)
+
+    def get_realizations_for_vp(self, vp):
+        return self.viewpoints_realizations[vp]
+
+    def random_starting_note(self):
+        # unchanged (uses your previous address scheme)
+        starting_vp = (-1, 0)
+        starting_conts = self.get_realizations_for_vp(starting_vp)
+        start = random.choice(starting_conts)
+        return start
+
+    # def sample_sequence_that_ends(self, start_vp, length=50):
+    #     pgm = self.build_bp_graph(length)
+    #     pgm.set_value('x1', self.index_of_vp(start_vp))
+    #     pgm.set_value('x' + str(length + 2), self.index_of_vp(self.end_padding))
+    #     try:
+    #         vp_seq = self.sample_vp_sequence_with_bp(start_vp, length, pgm)
+    #     except NoSolutionError:
+    #         return None
+    #     return vp_seq
+
+    from typing import Dict, Optional
+    # assumes: from ctor.belief_propag import NoSolutionError
+
+    def sample_sequence_old(
+            self,
+            length: int,
+            prefix=None,
+            constraints: Optional[Dict[int, object]] = None,
+            *,
+            relax_prefix_on_fail: bool = True,
+            relax_pos0_on_fail: bool = True,
+            raise_on_fail: bool = False,
+    ):
+        """
+        Sample a viewpoint sequence of given `length`.
+
+        Parameters
+        ----------
+        prefix : sequence of notes/viewpoints forming the *last played* phrase.
+                 Used only to derive a soft start bias (start_vp = viewpoint of prefix[-1]).
+        constraints : dict[int -> viewpoint]
+            Hard constraints at positions (0-based). Values are viewpoint objects (NOT indices).
+
+        Relaxation logic (if NoSolutionError):
+          1) Try with all constraints + soft start bias from prefix (or from constraints[0] if present).
+          2) If fail and relax_prefix_on_fail: retry with start bias removed.
+          3) If still fail and relax_pos0_on_fail and 0 in constraints: drop the hard constraint at pos 0, keep bias off.
+        """
+
+        constraints = constraints or {}
+
+        def _build_graph(active_constraints: Dict[int, object]):
+            pgm = self.build_bp_graph(length)
+            for pos, vp in active_constraints.items():
+                var_name = f"x{pos + 1}"
+                pgm.set_value(var_name, self.index_of_vp(vp))  # vp -> index
+            return pgm
+
+        # Soft start bias from the prefix (viewpoint object), unless overridden by a hard constraint at pos 0
+        start_vp = None
+        if prefix:
+            start_vp = self.get_viewpoint(prefix[-1])
+        else:
+            if 0 in constraints:
+                start_vp = constraints[0]  # hard constraint at pos0 overrides the soft bias
+
+        last_error = None
+
+        # Attempt 1: all constraints + (maybe) start bias
+        try:
+            pgm = _build_graph(constraints)
+            seq = self.sample_vp_sequence_with_bp(length, start_vp, pgm)
+            if seq is not None:
+                if prefix:
+                    return seq[1:]
+                else:
+                    return seq
+        except NoSolutionErrorInBP as e:
+            last_error = e
+
+        if prefix:
+            print('give up prefix constraint (continuation)')
+        # Attempt 2: relax the prefix bias only
+        if relax_prefix_on_fail and start_vp is not None:
+            try:
+                pgm = _build_graph(constraints)
+                seq = self.sample_vp_sequence_with_bp(length, None, pgm)
+                if seq is not None:
+                    return seq
+            except NoSolutionErrorInBP as e:
+                last_error = e
+
+        print('give up start sequence constraint')
+        # Attempt 3: also drop the hard constraint at position 0 (if any)
+        if relax_pos0_on_fail and 0 in constraints:
+            try:
+                loosened = {k: v for k, v in constraints.items() if k != 0}
+                pgm = _build_graph(loosened)
+                seq = self.sample_vp_sequence_with_bp(length, None, pgm)
+                if seq is not None:
+                    return seq
+            except NoSolutionErrorInBP as e:
+                last_error = e
+
+        if raise_on_fail:
+            raise NoSolutionErrorInBP("No solution after relaxing prefix bias and pos0 constraint.") from last_error
+        return None
+
+    def sample_sequence(
+            self,
+            length: int,
+            prefix=None,
+            constraints: Optional[Dict[int, object]] = None,
+            *,
+            relax_prefix_on_fail: bool = True,
+            relax_pos0_on_fail: bool = True,
+            raise_on_fail: bool = False,
+    ):
+        """
+        Sample a viewpoint sequence of given `length`.
+
+        Parameters
+        ----------
+        prefix : sequence of notes/viewpoints forming the *last played* phrase.
+                 Used only to derive a soft start bias (start_vp = viewpoint of prefix[-1]).
+        constraints : dict[int -> viewpoint]
+            Hard constraints at positions (0-based). Values are viewpoint objects (NOT indices).
+
+        Relaxation logic (if NoSolutionError):
+          1) Try with all constraints + soft start bias from prefix (or from constraints[0] if present).
+          2) If fail and relax_prefix_on_fail: retry with start bias removed.
+          3) If still fail and relax_pos0_on_fail and 0 in constraints: drop the hard constraint at pos 0, keep bias off.
+        """
+
+        constraints = constraints or {}
+
+        def _build_graph(graph_length, active_constraints: Dict[int, object]):
+            pgm = self.build_bp_graph(graph_length)
+            for pos, vp in active_constraints.items():
+                var_name = f"x{pos + 1}"
+                pgm.set_value(var_name, self.index_of_vp(vp))  # vp -> index
+            return pgm
+
+        # Soft start bias from the prefix (viewpoint object), unless overridden by a hard constraint at pos 0
+        start_vp = None
+        if prefix  is None:
+            pgm = _build_graph(length, constraints)
+            seq = self.sample_vp_sequence_with_bp(length, None, pgm)
+            return seq
+
+        # Attempt 1: all constraints + start bias and translate constraints by 1 and length + 1
+        translated_constraints = {k + 1: v for k, v in constraints.items()}
+        start_vp = self.get_viewpoint(prefix[-1])
+        last_error = None
+        try:
+            pgm = _build_graph(length + 1, translated_constraints)
+            seq = self.sample_vp_sequence_with_bp(length + 1, start_vp, pgm)
+            if seq is not None:
+                return seq[1:]
+            # returns the sequence except the prefix
+        except NoSolutionErrorInBP as e:
+            last_error = e
+
+        print('give up prefix constraint (continuation)')
+        # Attempt 2: relax the prefix bias only
+        if relax_prefix_on_fail:
+            try:
+                translated_constraints = {k + 1: v for k, v in constraints.items()}
+                pgm = _build_graph(length + 1, translated_constraints)
+                if 1 in constraints:
+                    start_vp = constraints[1]
+                else:
+                    start_vp = self.start_padding
+                seq = self.sample_vp_sequence_with_bp(length + 1, start_vp, pgm)
+                if seq is not None:
+                    return seq[1:] # returns the sequence except the startvp
+            except NoSolutionErrorInBP as e:
+                last_error = e
+
+        print('give up start sequence constraint')
+        # Attempt 3: also drop the hard constraint at position 0 (if any)
+        if relax_pos0_on_fail and 0 in constraints:
+            try:
+                loosened = {k: v for k, v in constraints.items() if k != 0}
+                pgm = _build_graph(length, loosened)
+                seq = self.sample_vp_sequence_with_bp(length, None, pgm)
+                if seq is not None:
+                    return seq
+            except NoSolutionErrorInBP as e:
+                last_error = e
+
+        if raise_on_fail:
+            raise NoSolutionErrorInBP("No solution after relaxing prefix bias and pos0 constraint.") from last_error
+        return None
+
+    # length of bp graph is length + 2: plus the start (possibly the end of an existing sequence) and plus the end viewpoint
+    def build_bp_graph(self, length):
+        string = ""
+        for i in range(length):
+            string = string + "p(x" + str(i + 1) + ")"
+        for i in range(2, length + 1):
+            string = string + "p(x" + str(i) + "|x" + str(i - 1) + ")"
+        pgm = PGM.from_string(string)
+        mat = LabeledArray(np.array(self.get_first_order_matrix()).transpose(), ["x2", "x1"], )
+        m = self.voc_size()
+        data_dict = {}
+        for i in range(length):
+            variable_dist = np.random.uniform(1 / m, 1 / m, m)
+            # should avoid start and end values
+            variable_dist[self.index_of_vp(self.start_padding)] = 0
+            variable_dist[self.index_of_vp(self.end_padding)] = 0
+            variable_dist /= variable_dist.sum()
+            data_dict["p(x" + str(i + 1) + ")"] = LabeledArray(np.array(variable_dist), ["x" + str(i + 1)])
+            data_dict["p(x" + str(i + 2) + "|x" + str(i + 1) + ")"] = LabeledArray(
+                mat.array, ["x" + str(i + 2), "x" + str(i + 1)]
+            )
+        pgm.set_data(data_dict)
+        return pgm
+
+    @staticmethod
+    def is_ok(marginal):
+        for x in marginal:
+            if np.isnan(x):
+                return False
+        return True
+
+    def sample_vp_sequence_with_bp(self, length, first_vp, pgm):
+        if length < 0:
+            print(f"impossible to sample a sequence of length {length}")
+            return None
+
+        if first_vp is not None:
+            current_seq = [first_vp]
+        else:
+            try:
+                marginal_1 = Messages().marginal(pgm.variable_from_name('x1'))
+                vp = self.random_vp_with_probs(marginal_1)
+                current_seq = [vp]
+            except NoSolutionErrorInBP:
+                return None
+        try:
+            pgm.set_value('x1', self.index_of_vp(current_seq[0]))
+        except NoSolutionErrorInBP:
+            return None
+        # generate the rest of the sequence
+        first_order_matrix = self.get_first_order_matrix()
+        for i in range(length - 1):
+            pgm_variable = pgm.variable_from_name('x' + str(i + 2))
+            try:
+                marginal_i = Messages().marginal(pgm_variable)
+            except NoSolutionErrorInBP:
+                return None
+            markov_proba = first_order_matrix[self.index_of_vp(current_seq[-1])]
+            product_proba = marginal_i * markov_proba
+            cont = self.get_continuation_with_bp(current_seq, product_proba)
+            if cont is None:
+                cont = self.random_initial_vp()
+            current_seq.append(cont)
+            pgm.set_value('x' + str(i + 2), self.index_of_vp(cont))
+        return current_seq
+
+    def sample_vp_sequence(self, first_vp, length, last_vp):
+        current_seq = [first_vp]
+        if length >= 0:
+            for _ in range(length):
+                cont = self.get_continuation(current_seq)
+                if cont is None:
+                    cont = self.random_initial_vp()
+                current_seq.append(cont)
+            return current_seq
+        while True:
+            cont = self.get_continuation(current_seq)
+            if cont is None:
+                cont = self.random_initial_vp()
+            if cont == last_vp:
+                if cont != self.end_padding:
+                    current_seq.append(cont)
+                return current_seq
+            current_seq.append(cont)
+
+    def get_continuation(self, current_seq):
+        vp_to_skip = None
+        now = self.global_step if self.decay_freeze_at is None else self.decay_freeze_at
+        for k in range(self.kmax, 0, -1):
+            if k > len(current_seq):
+                continue
+            ctx = tuple(current_seq[-k:])
+            mc = self.ctx_to_continuations.get(ctx)
+            if not mc:
+                continue
+            w = mc.weights(now, self.period_mode)
+            if not w:
+                continue
+            # keep your singleton-skip heuristic
+            if len(w) == 1 and k > 1:
+                if random.random() > (1 / (k + 1)):
+                    vp_to_skip = next(iter(w))
+                    continue
+                else:
+                    vp_to_skip = None
+            if vp_to_skip is not None and k > 1 and vp_to_skip in w:
+                w = {kk: vv for kk, vv in w.items() if kk != vp_to_skip}
+                if not w:
+                    continue
+            items, weights = zip(*w.items())
+            j = self.rng.choices(items, weights=weights, k=1)[0]
+            return self.all_unique_viewpoints[j]
+        print("no continuation found")
+        return None
+
+    def get_continuation_with_bp(self, current_seq, probs):
+        vp_to_skip = None
+        now = self.global_step if self.decay_freeze_at is None else self.decay_freeze_at
+        for k in range(self.kmax, 0, -1):
+            if k > len(current_seq):
+                continue
+            ctx = tuple(current_seq[-k:])
+            mc = self.ctx_to_continuations.get(ctx)
+            if not mc:
+                continue
+            w = mc.weights(now, self.period_mode)
+            if not w:
+                continue
+            # mask with BP posterior > 0
+            mask = [p > 0 for p in probs]
+            w = {j: v for j, v in w.items() if mask[j]}
+            if not w:
+                continue
+            if len(w) == 1 and k > 1:
+                if random.random() > (1 / (k + 1)):
+                    vp_to_skip = next(iter(w))
+                    continue
+                else:
+                    vp_to_skip = None
+            if vp_to_skip is not None and k > 1 and vp_to_skip in w:
+                del w[vp_to_skip]
+                if not w:
+                    continue
+            items, weights = zip(*w.items())
+            j = self.rng.choices(items, weights=weights, k=1)[0]
+            return self.all_unique_viewpoints[j]
+        print("no continuation found")
+        return None
+
+    def show_conts_structure(self):
+        # counts per context length
+        by_len = defaultdict(int)
+        for ctx in self.ctx_to_continuations.keys():
+            by_len[len(ctx)] += 1
+        for k in range(1, self.kmax + 1):
+            print(f"size of contexts of size {k}: {by_len.get(k, 0)}")
+
+        # sparsity of order-1
+        voc_size = self.voc_size()
+        now = self.global_step if self.decay_freeze_at is None else self.decay_freeze_at
+        min_size = voc_size
+        max_size = 0
+        for vp in self.all_unique_viewpoints:
+            mc = self.ctx_to_continuations.get((vp,), None)
+            csz = mc.nonzero_options(now, self.period_mode) if mc else 0
+            min_size = min(min_size, csz)
+            max_size = max(max_size, csz)
+        print(f"voc size: {voc_size}")
+        print(f"min order 1 size: {min_size}, max: {max_size}")
+        total = 0
+        for k in self.viewpoints_realizations:
+            total += len(self.viewpoints_realizations[k])
+        print(f"average nb of vp realizations: {total / voc_size if voc_size else 0.0}")
+
+if __name__ == '__main__':
+    # computes chord sequences of length 8 starting and ending with, say, C and with a F#7 in the middle
+    with open('../data/chord_sequences.txt', 'r') as file:
+        seqs = file.readlines()[:200]
+    seqs = [seq.split(';')[1:-1] for seq in seqs]
+    seqs = [[chord.strip() for chord in seq] for seq in seqs]
+    vo = Variable_order_Markov(None, None, kmax=3)
+    for seq in seqs:
+        vo.learn_sequence(seq)
+
+    length = 8
+    for i in range(20):
+        seq = vo.sample_sequence(length, constraints={0: vo.get_viewpoint('C'), int(length/2): vo.get_viewpoint('F#7'), length - 1: vo.get_viewpoint('C')})
+        result = ' '.join(seq)
+        print(result)

backend/vendor/midi_stuff/__init__.py

@@ -0,0 +1,2 @@
+"""Vendored subset of the Continuator midi_stuff package."""
+

backend/vendor/midi_stuff/mini_muse.py

@@ -0,0 +1,212 @@
+import mido
+import numpy as np
+
+
+class Note:
+    def __init__(self, pitch, velocity, duration, start_time=0):
+        self.pitch = pitch
+        self.velocity = velocity
+        # the duration in the original sequence in beats, assuming 120bpm
+        self.duration = duration
+        # the start time in the original sequence in beats, assuming 120bpm
+        self.start_time = start_time
+        # time between start and the start of preceding note, always > 0
+        self.preceding_start_delta = 0  # in beats, assuming 120bpm
+        # time between start and the end of preceding note. Negative if overlaps with preceding
+        self.preceding_end_delta = 0  # in beats, assuming 120bpm
+        # time between start of next note and end. Negative if overlaps with next
+        self.next_start_delta = 0  # in beats, assuming 120bpm
+        # time between end of next note and end
+        self.next_end_delta = 0  # in beats, assuming 120bpm
+
+    def __str__(self):
+        return f"{self.pitch} @ [{self.start_time}, {self.get_end_time()}]"
+
+    def __repr__(self):
+        return f"{self.pitch} @ [{self.start_time}, {self.get_end_time()}]"
+
+    def set_duration(self, d):
+        self.duration = d
+
+    def set_start_time(self, t):
+        self.start_time = t
+
+    def overlaps_left(self):
+        # if overlap is greater than half the duration
+        return self.preceding_end_delta < 0
+
+    def overlaps_right(self):
+        # if overlap is greater than half the duration
+        return self.next_start_delta < 0
+
+    def transpose(self, t):
+        note = self.copy()
+        note.pitch = self.pitch + t
+        return note
+
+    def copy(self):
+        new_note = Note(self.pitch, self.velocity, self.duration, start_time=self.start_time)
+        new_note.preceding_start_delta = self.preceding_start_delta
+        new_note.preceding_end_delta = self.preceding_end_delta
+        new_note.next_start_delta = self.next_start_delta
+        new_note.next_end_delta = self.next_end_delta
+        return new_note
+
+    def get_end_time(self):
+        return self.start_time + self.duration
+
+    def is_compatible_with(self, note):
+        # returns true if self and note have same polyphonic status
+        return self.overlaps_right() == note.overlaps_left()
+
+    def get_status_right(self):
+        if self.next_end_delta <= 0:
+            return 'inside'
+        if self.next_start_delta < 0:
+            return 'overlaps'
+        return 'after'
+
+    def get_status_left(self):
+        if self.preceding_end_delta >= 0:
+            return 'before'
+        if abs(self.preceding_end_delta) < self.duration:
+            return 'overlaps'
+        return 'contains'
+
+    def is_similar_realization(self, note):
+        if self.pitch != note.pitch:
+            return False
+        if self.velocity != note.velocity:
+            return False
+        if self.duration != note.duration:
+            return False
+        if self.preceding_end_delta != note.preceding_end_delta:
+            return False
+        if self.preceding_start_delta != note.preceding_start_delta:
+            return False
+        if self.next_start_delta != note.next_start_delta:
+            return False
+        if self.next_end_delta != note.next_end_delta:
+            return False
+        return True
+
+
+class Realized_Chord:
+    # is a list of Note
+    def __init__(self, notes):
+        self.notes = notes
+
+    def get_highest_pitch(self):
+        highest = 0
+        for note in self.notes:
+            highest = max(highest, note.pitch)
+        return highest
+
+    def get_lowest_pitch(self):
+        lowest = 128
+        for note in self.notes:
+            lowest = min(lowest, note.pitch)
+        return lowest
+
+    def append(self, note):
+        self.notes.append(note)
+
+    def get_nb_notes(self):
+        return len(self.notes)
+
+    def transpose_by(self, i):
+        transposed_notes = [n.transpose(i) for n in self.notes]
+        return Realized_Chord(transposed_notes)
+
+    def create_mido_sequence(self):
+        mid = mido.MidiFile()
+        track = mido.MidiTrack()
+        mid.tracks.append(track)
+        # create a new sequence with the right start_times
+        # create all mido messages and sort them
+        mido_sequence = []
+        for note in self.notes:
+            try:
+                mido_sequence.append(
+                    mido.Message(
+                        "note_on",
+                        note=note.pitch,
+                        velocity=note.velocity,
+                        time=note.start_time,
+                    )
+                )
+            except:
+                print("Something went wrong")
+            mido_sequence.append(
+                mido.Message(
+                    "note_off",
+                    note=note.pitch,
+                    velocity=0,
+                    time=note.start_time + note.duration,
+                )
+            )
+        mido_sequence.sort(key=lambda messg: messg.time)
+        current_time = 0
+        # converts beats into ticks, assuming 480 ticks per second
+        for msg in mido_sequence:
+            delta_in_beats = msg.time - current_time
+            delta_in_ticks = int(mid.ticks_per_beat * delta_in_beats)
+            msg.time = delta_in_ticks
+            track.append(msg)
+            current_time += delta_in_beats
+        return mid
+
+    @classmethod
+    def extract_notes(cls, midi_file):
+        mid = mido.MidiFile(midi_file)
+        resolution = mid.ticks_per_beat
+        notes = []
+        pending_notes = np.empty(128, dtype=object)
+        pending_start_times = np.zeros(128)
+        current_time = 0
+        for track in mid.tracks:
+            for msg in track:
+                current_time += 2 * mido.tick2second(msg.time, ticks_per_beat=resolution, tempo=500000)  # in beats
+                if msg.type == "note_on" and msg.velocity > 0:
+                    new_note = Note(msg.note, msg.velocity, 0)
+                    notes.append(new_note)  # Store MIDI note number
+                    pending_notes[msg.note] = new_note
+                    pending_start_times[msg.note] = current_time
+                    new_note.set_start_time(current_time)
+                    new_note.set_duration(1)  # beat
+                if msg.type == "note_off" or (msg.type == "note_on" and msg.velocity == 0):
+                    if pending_notes[msg.note] is None:
+                        print("found 0 velocity note, skipping it")
+                        continue
+                    pending_note = pending_notes[msg.note]
+                    duration = current_time - pending_start_times[msg.note]
+                    pending_note.set_duration(duration)
+                    pending_notes[msg.note] = None
+                    pending_start_times[msg.note] = 0
+        return np.array(notes)
+
+    @classmethod
+    def create_chords(cls, midi_file, transpose=False):
+        notes = cls.extract_notes(midi_file)
+        chords = []
+        current_chord = Realized_Chord([])
+        max_time_current_chord = 0
+        for note in notes:
+            if note.start_time > max_time_current_chord:
+                if current_chord.get_nb_notes() > 0:
+                    chords.append(current_chord)
+                current_chord = Realized_Chord([note])
+                max_time_current_chord = max(max_time_current_chord, note.get_end_time())
+            else:
+                current_chord.append(note)
+                max_time_current_chord = max(max_time_current_chord, note.get_end_time())
+        if current_chord.get_nb_notes() > 0:
+            chords.append(current_chord)
+
+        if transpose:
+            transposed = []
+            for i in range(-5, 7):
+                if i != 0:
+                    transposed = transposed + [ch.transpose_by(i) for ch in chords]
+            chords = chords + transposed
+        return chords

frontend/app.js

@@ -0,0 +1,1183 @@
+const BROWSER_SYNTH_ID = "__browser_synth__";
+const PHRASE_TIMEOUT_MS = 1000;
+
+const elements = {
+  serverStatus: document.querySelector("#server-status"),
+  sessionStatus: document.querySelector("#session-status"),
+  sessionId: document.querySelector("#session-id"),
+  midiStatus: document.querySelector("#midi-status"),
+  phraseStatus: document.querySelector("#phrase-status"),
+  selectedInputName: document.querySelector("#selected-input-name"),
+  selectedOutputName: document.querySelector("#selected-output-name"),
+  lastMidiEvent: document.querySelector("#last-midi-event"),
+  capturedEventCount: document.querySelector("#captured-event-count"),
+  capturedNoteCount: document.querySelector("#captured-note-count"),
+  generatedEventCount: document.querySelector("#generated-event-count"),
+  generatedNoteCount: document.querySelector("#generated-note-count"),
+  messageBox: document.querySelector("#message-box"),
+  historyList: document.querySelector("#history-list"),
+  memoryList: document.querySelector("#memory-list"),
+  memorySummary: document.querySelector("#memory-summary"),
+  memoryHint: document.querySelector("#memory-hint"),
+  memoryRibbon: document.querySelector("#memory-ribbon"),
+  inputRoll: document.querySelector("#input-roll"),
+  outputRoll: document.querySelector("#output-roll"),
+  settingsSummary: document.querySelector("#settings-summary"),
+  historyTab: document.querySelector("#history-tab"),
+  memoryTab: document.querySelector("#memory-tab"),
+  historyPanel: document.querySelector("#history-panel"),
+  memoryPanel: document.querySelector("#memory-panel"),
+  viewTabs: document.querySelectorAll("[data-view-tab]"),
+  midiInputSelect: document.querySelector("#midi-input-select"),
+  midiOutputSelect: document.querySelector("#midi-output-select"),
+  learnInputToggle: document.querySelector("#learn-input-toggle"),
+  autoSendToggle: document.querySelector("#auto-send-toggle"),
+  transposeToggle: document.querySelector("#transpose-toggle"),
+  forgetToggle: document.querySelector("#forget-toggle"),
+  keepLastInput: document.querySelector("#keep-last-input"),
+  decayModeSelect: document.querySelector("#decay-mode-select"),
+  createSessionButton: document.querySelector("#create-session-button"),
+  resetSessionButton: document.querySelector("#reset-session-button"),
+  applySettingsButton: document.querySelector("#apply-settings-button"),
+  connectMidiButton: document.querySelector("#connect-midi-button"),
+  refreshMidiButton: document.querySelector("#refresh-midi-button"),
+  sendPhraseButton: document.querySelector("#send-phrase-button"),
+  replayGeneratedButton: document.querySelector("#replay-generated-button"),
+  clearPhraseButton: document.querySelector("#clear-phrase-button"),
+};
+
+const state = {
+  midiAccess: null,
+  activeInputId: null,
+  sessionId: null,
+  sessionConfiguration: null,
+  lastCapturedPhrase: [],
+  lastGeneratedPhrase: null,
+  historyItems: [],
+  memoryItems: [],
+  activeActivityView: "history",
+};
+
+class BrowserSynth {
+  constructor() {
+    this.context = null;
+    this.master = null;
+    this.activeVoices = new Map();
+  }
+
+  async ensureContext() {
+    if (!this.context) {
+      this.context = new window.AudioContext();
+      this.master = new window.GainNode(this.context, { gain: 0.18 });
+      this.master.connect(this.context.destination);
+    }
+    if (this.context.state === "suspended") {
+      await this.context.resume();
+    }
+  }
+
+  key(note, channel) {
+    return `${channel}:${note}`;
+  }
+
+  midiToFrequency(note) {
+    return 440 * 2 ** ((note - 69) / 12);
+  }
+
+  async play(events) {
+    if (!events?.length) {
+      return;
+    }
+
+    await this.ensureContext();
+    let cursor = 0;
+    const startAt = this.context.currentTime + 0.05;
+
+    for (const event of events) {
+      cursor += event.delta_seconds;
+      const at = startAt + cursor;
+      const key = this.key(event.note, event.channel);
+
+      if (event.type === "note_on" && event.velocity > 0) {
+        const oscillator = new OscillatorNode(this.context, {
+          type: "triangle",
+          frequency: this.midiToFrequency(event.note),
+        });
+        const gain = new GainNode(this.context, { gain: 0.0001 });
+        oscillator.connect(gain).connect(this.master);
+        gain.gain.setValueAtTime(0.0001, at);
+        gain.gain.exponentialRampToValueAtTime(
+          Math.max(0.03, (event.velocity / 127) * 0.2),
+          at + 0.015,
+        );
+        oscillator.start(at);
+
+        const existing = this.activeVoices.get(key) || [];
+        existing.push({ oscillator, gain });
+        this.activeVoices.set(key, existing);
+      } else {
+        const voices = this.activeVoices.get(key);
+        if (!voices?.length) {
+          continue;
+        }
+        const voice = voices.shift();
+        voice.gain.gain.cancelScheduledValues(at);
+        voice.gain.gain.setValueAtTime(0.06, at);
+        voice.gain.gain.exponentialRampToValueAtTime(0.0001, at + 0.08);
+        voice.oscillator.stop(at + 0.1);
+        if (!voices.length) {
+          this.activeVoices.delete(key);
+        }
+      }
+    }
+  }
+}
+
+class PhraseRecorder {
+  constructor(timeoutMs, onUpdate, onComplete) {
+    this.timeoutMs = timeoutMs;
+    this.onUpdate = onUpdate;
+    this.onComplete = onComplete;
+    this.reset();
+  }
+
+  reset() {
+    this.events = [];
+    this.pendingNotes = new Set();
+    this.lastTimestamp = null;
+    if (this.timer) {
+      window.clearTimeout(this.timer);
+    }
+    this.timer = null;
+  }
+
+  snapshot() {
+    return this.events.map((event) => ({ ...event }));
+  }
+
+  handleMessage(messageEvent) {
+    const [statusByte, note, rawVelocity = 0] = [...messageEvent.data];
+    const status = statusByte & 0xf0;
+    const channel = statusByte & 0x0f;
+    let type = null;
+    let velocity = rawVelocity;
+
+    if (status === 0x90 && velocity > 0) {
+      type = "note_on";
+    } else if (status === 0x80 || (status === 0x90 && velocity === 0)) {
+      type = "note_off";
+      velocity = 0;
+    } else {
+      return;
+    }
+
+    const timestamp =
+      typeof messageEvent.receivedTime === "number"
+        ? messageEvent.receivedTime
+        : window.performance.now();
+    const deltaSeconds =
+      this.lastTimestamp == null
+        ? 0
+        : Math.max(0, (timestamp - this.lastTimestamp) / 1000);
+    this.lastTimestamp = timestamp;
+
+    const event = {
+      type,
+      note,
+      velocity,
+      channel,
+      delta_seconds: roundNumber(deltaSeconds),
+    };
+
+    const key = `${channel}:${note}`;
+    if (type === "note_on") {
+      this.pendingNotes.add(key);
+    } else {
+      this.pendingNotes.delete(key);
+    }
+
+    this.events.push(event);
+    this.onUpdate?.(this.snapshot(), false);
+    this.scheduleCompletionCheck(timestamp);
+  }
+
+  scheduleCompletionCheck(nowTimestamp) {
+    if (this.timer) {
+      window.clearTimeout(this.timer);
+    }
+
+    if (!this.events.length || this.lastTimestamp == null) {
+      return;
+    }
+
+    if (this.pendingNotes.size) {
+      return;
+    }
+
+    const elapsed = nowTimestamp - this.lastTimestamp;
+    if (elapsed >= this.timeoutMs) {
+      this.completePhrase();
+      return;
+    }
+
+    this.timer = window.setTimeout(() => {
+      this.completePhrase();
+    }, this.timeoutMs - elapsed);
+  }
+
+  completePhrase() {
+    if (!this.events.length || this.pendingNotes.size || this.lastTimestamp == null) {
+      return;
+    }
+
+    const nowTimestamp = window.performance.now();
+    const elapsed = nowTimestamp - this.lastTimestamp;
+    if (elapsed < this.timeoutMs) {
+      this.scheduleCompletionCheck(nowTimestamp);
+      return;
+    }
+
+    const phrase = this.snapshot();
+    this.reset();
+    this.onComplete?.(phrase);
+    this.onUpdate?.(phrase, true);
+  }
+}
+
+const synth = new BrowserSynth();
+const recorder = new PhraseRecorder(
+  PHRASE_TIMEOUT_MS,
+  (events, completed) => {
+    const notes = eventsToNotes(events);
+    renderCapturedStats(events, notes, completed);
+  },
+  async (phrase) => {
+    state.lastCapturedPhrase = phrase;
+    const notes = eventsToNotes(phrase);
+    renderCapturedStats(phrase, notes, true);
+    setPhraseMessage(
+      `Phrase complete: ${phrase.length} events / ${notes.length} notes captured.`,
+    );
+    if (elements.autoSendToggle.checked) {
+      await sendCurrentPhrase();
+    }
+  },
+);
+
+function roundNumber(value) {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}
+
+function formatDurationSeconds(value) {
+  const duration = Number(value) || 0;
+  return duration >= 10 ? `${duration.toFixed(0)}s` : `${duration.toFixed(1)}s`;
+}
+
+function setPhraseMessage(message, danger = false) {
+  elements.messageBox.textContent = message;
+  elements.messageBox.style.color = danger ? "var(--danger)" : "var(--muted)";
+}
+
+function setSessionStatus(label) {
+  elements.sessionStatus.textContent = label;
+}
+
+function setMidiStatus(label) {
+  elements.midiStatus.textContent = label;
+}
+
+function setPhraseStatus(label) {
+  elements.phraseStatus.textContent = label;
+}
+
+function setSelectedInputName(label) {
+  elements.selectedInputName.textContent = label;
+}
+
+function setSelectedOutputName(label) {
+  elements.selectedOutputName.textContent = label;
+}
+
+function setLastMidiEvent(label) {
+  elements.lastMidiEvent.textContent = label;
+}
+
+function normalizedKeepLastInputs(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    return 20;
+  }
+  return Math.min(500, Math.max(1, Math.round(parsed)));
+}
+
+function readSessionSettingsFromControls() {
+  return {
+    learn_input: elements.learnInputToggle.checked,
+    transposition: elements.transposeToggle.checked,
+    forget_past: elements.forgetToggle.checked,
+    keep_last_inputs: normalizedKeepLastInputs(elements.keepLastInput.value),
+    decay_mode: elements.decayModeSelect.value,
+  };
+}
+
+function describeSessionSettings(settings) {
+  const transposeLabel = settings.transposition ? "Transpose on" : "Transpose off";
+  const memoryLabel = settings.forget_past
+    ? `Keep last ${settings.keep_last_inputs} phrases`
+    : "Keep full memory";
+  const decayLabel = `Decay ${settings.decay_mode}`;
+  return [transposeLabel, memoryLabel, decayLabel];
+}
+
+function renderSessionSettingsSummary() {
+  const labels = describeSessionSettings(readSessionSettingsFromControls());
+  elements.settingsSummary.innerHTML = labels
+    .map((label) => `<span class="settings-chip">${label}</span>`)
+    .join("");
+}
+
+function updateKeepLastFieldState() {
+  const enabled = elements.forgetToggle.checked;
+  elements.keepLastInput.disabled = !enabled;
+}
+
+function syncSettingsControls(configuration) {
+  if (!configuration) {
+    return;
+  }
+
+  state.sessionConfiguration = configuration;
+  elements.learnInputToggle.checked = configuration.learn_input;
+  elements.transposeToggle.checked = configuration.transposition;
+  elements.forgetToggle.checked = configuration.forget_past;
+  elements.keepLastInput.value = String(configuration.keep_last_inputs);
+  elements.decayModeSelect.value = configuration.decay_mode;
+  updateKeepLastFieldState();
+  renderSessionSettingsSummary();
+}
+
+function updateSessionActionState() {
+  elements.applySettingsButton.disabled = !state.sessionId;
+}
+
+function setActivityView(view) {
+  state.activeActivityView = view;
+  const showHistory = view === "history";
+  elements.historyTab.classList.toggle("is-active", showHistory);
+  elements.historyTab.setAttribute("aria-selected", String(showHistory));
+  elements.historyPanel.hidden = !showHistory;
+  elements.memoryTab.classList.toggle("is-active", !showHistory);
+  elements.memoryTab.setAttribute("aria-selected", String(!showHistory));
+  elements.memoryPanel.hidden = showHistory;
+}
+
+function previewPhrasePayload(payload, kind, message) {
+  if (kind === "generated") {
+    state.lastGeneratedPhrase = payload;
+    renderGeneratedStats(payload);
+  } else {
+    state.lastCapturedPhrase = payload.events;
+    renderCapturedStats(payload.events, payload.notes, true);
+  }
+  setPhraseMessage(message);
+}
+
+function renderCapturedStats(events, notes, completed) {
+  elements.capturedEventCount.textContent = String(events.length);
+  elements.capturedNoteCount.textContent = String(notes.length);
+  setPhraseStatus(completed ? "Phrase ready" : "Listening");
+  drawPianoRoll(elements.inputRoll, notes, "#6dd3ce", "Input phrase");
+}
+
+function renderGeneratedStats(payload) {
+  elements.generatedEventCount.textContent = String(payload?.event_count || 0);
+  elements.generatedNoteCount.textContent = String(payload?.note_count || 0);
+  drawPianoRoll(
+    elements.outputRoll,
+    payload?.notes || [],
+    "#f4a261",
+    "Generated continuation",
+  );
+}
+
+function createHistoryMarkup(items) {
+  if (!items.length) {
+    return `<p class="muted">No phrases logged yet for this session.</p>`;
+  }
+
+  return items
+    .map(
+      (item, index) => `
+        <button class="history-item" data-history-index="${index}" type="button">
+          <span class="history-kind">${item.kind}</span>
+          <span class="history-meta">
+            <strong>${item.note_count} notes / ${item.event_count} events</strong>
+            <span>${item.created_at}</span>
+          </span>
+          <span class="history-index">open</span>
+        </button>
+      `,
+    )
+    .join("");
+}
+
+function attachHistoryEvents() {
+  elements.historyList.querySelectorAll("[data-history-index]").forEach((node) => {
+    node.addEventListener("click", () => {
+      const item = state.historyItems[Number(node.dataset.historyIndex)];
+      if (!item) {
+        return;
+      }
+
+      previewPhrasePayload(item.payload, item.kind, `Previewing ${item.kind} phrase from ${item.created_at}.`);
+    });
+  });
+}
+
+function renderHistory(items) {
+  state.historyItems = items;
+  elements.historyList.innerHTML = createHistoryMarkup(items);
+  attachHistoryEvents();
+}
+
+function createMemorySummaryMarkup(memory) {
+  if (!memory) {
+    return `<span class="settings-chip">No active memory yet</span>`;
+  }
+
+  const chips = [
+    `${memory.summary.active_phrase_count} active sequences`,
+    `${memory.summary.live_phrase_count} live`,
+  ];
+  if (memory.summary.seeded_phrase_count) {
+    chips.push(`${memory.summary.seeded_phrase_count} seed`);
+  }
+  chips.push(memory.configuration.transposition ? "Transpose on" : "Transpose off");
+  chips.push(
+    memory.configuration.forget_past
+      ? `Keep last ${memory.configuration.keep_last_inputs}`
+      : "Keep full memory",
+  );
+  chips.push(`Decay ${memory.configuration.decay_mode}`);
+
+  return chips.map((label) => `<span class="settings-chip">${label}</span>`).join("");
+}
+
+function createMemoryHint(memory) {
+  if (!memory) {
+    return "Create a session and play a phrase to inspect the active Continuator memory.";
+  }
+  if (!memory.summary.active_phrase_count) {
+    return memory.configuration.transposition
+      ? "No active sequences yet. When transpose is on, each learned phrase can appear as several active transposed variants."
+      : "No active sequences yet. Play a phrase to start filling the Continuator memory.";
+  }
+  return memory.configuration.transposition
+    ? "The ribbon reads oldest to newest. The list below starts with the newest active sequence, and transposed variants appear separately when transpose is enabled."
+    : "The ribbon reads oldest to newest. The list below starts with the newest active sequence. Click any item to preview it in the main piano roll.";
+}
+
+function createMemoryRibbonMarkup(items) {
+  if (!items.length) {
+    return "";
+  }
+
+  return items
+    .map((item, index) => {
+      const opacity = roundNumber(0.3 + ((index + 1) / items.length) * 0.6);
+      return `
+        <button
+          class="memory-ribbon-cell ${item.source}"
+          data-memory-index="${index}"
+          type="button"
+          title="Slot ${item.slot}: ${item.note_count} notes"
+          style="opacity: ${opacity};"
+        ></button>
+      `;
+    })
+    .join("");
+}
+
+function createMemoryMarkup(items) {
+  if (!items.length) {
+    return `<p class="muted">No active memory to show yet.</p>`;
+  }
+
+  return items
+    .slice()
+    .reverse()
+    .map((item) => {
+      const itemLabel = item.source === "seed" ? "Seed" : "Live";
+      return `
+        <button class="history-item memory-item" data-memory-index="${item.slot - 1}" type="button">
+          <span class="history-kind">${itemLabel} #${item.slot}</span>
+          <span class="history-meta">
+            <strong>${item.note_count} notes / ${formatDurationSeconds(item.duration_seconds)}</strong>
+            <span>Active slot ${item.slot} in current engine memory</span>
+          </span>
+          <span class="history-index">preview</span>
+        </button>
+      `;
+    })
+    .join("");
+}
+
+function attachMemoryEvents() {
+  const previewMemoryIndex = (rawIndex) => {
+    const item = state.memoryItems[Number(rawIndex)];
+    if (!item) {
+      return;
+    }
+    previewPhrasePayload(
+      item.payload,
+      "input",
+      `Previewing ${item.source} memory slot ${item.slot}.`,
+    );
+  };
+
+  elements.memoryList.querySelectorAll("[data-memory-index]").forEach((node) => {
+    node.addEventListener("click", () => {
+      previewMemoryIndex(node.dataset.memoryIndex);
+    });
+  });
+
+  elements.memoryRibbon.querySelectorAll("[data-memory-index]").forEach((node) => {
+    node.addEventListener("click", () => {
+      previewMemoryIndex(node.dataset.memoryIndex);
+    });
+  });
+}
+
+function renderMemory(memory) {
+  state.memoryItems = memory?.items || [];
+  elements.memorySummary.innerHTML = createMemorySummaryMarkup(memory);
+  elements.memoryHint.textContent = createMemoryHint(memory);
+  elements.memoryRibbon.innerHTML = createMemoryRibbonMarkup(state.memoryItems);
+  elements.memoryList.innerHTML = createMemoryMarkup(state.memoryItems);
+  attachMemoryEvents();
+}
+
+function drawPianoRoll(canvas, notes, accent, emptyLabel) {
+  const rect = canvas.getBoundingClientRect();
+  const dpr = window.devicePixelRatio || 1;
+  const width = Math.max(320, Math.floor(rect.width || 640));
+  const height = Math.max(180, Math.floor(rect.height || 244));
+  canvas.width = width * dpr;
+  canvas.height = height * dpr;
+
+  const ctx = canvas.getContext("2d");
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  ctx.clearRect(0, 0, width, height);
+
+  const background = ctx.createLinearGradient(0, 0, 0, height);
+  background.addColorStop(0, "rgba(255, 255, 255, 0.06)");
+  background.addColorStop(1, "rgba(255, 255, 255, 0.015)");
+  ctx.fillStyle = background;
+  ctx.fillRect(0, 0, width, height);
+
+  ctx.strokeStyle = "rgba(255, 255, 255, 0.06)";
+  ctx.lineWidth = 1;
+  for (let index = 1; index < 8; index += 1) {
+    const x = (index / 8) * width;
+    ctx.beginPath();
+    ctx.moveTo(x, 0);
+    ctx.lineTo(x, height);
+    ctx.stroke();
+  }
+  for (let index = 1; index < 6; index += 1) {
+    const y = (index / 6) * height;
+    ctx.beginPath();
+    ctx.moveTo(0, y);
+    ctx.lineTo(width, y);
+    ctx.stroke();
+  }
+
+  if (!notes?.length) {
+    ctx.fillStyle = "rgba(236, 244, 239, 0.45)";
+    ctx.font = '600 14px "Avenir Next", "Segoe UI Variable", sans-serif';
+    ctx.fillText(emptyLabel, 20, height / 2);
+    return;
+  }
+
+  const minPitch = Math.max(24, Math.min(...notes.map((note) => note.pitch)) - 2);
+  const maxPitch = Math.min(108, Math.max(...notes.map((note) => note.pitch)) + 2);
+  const totalDuration = Math.max(
+    2,
+    ...notes.map((note) => note.end_seconds || note.start_seconds + note.duration_seconds),
+  );
+  const pitchRange = Math.max(1, maxPitch - minPitch + 1);
+
+  ctx.fillStyle = accent;
+  ctx.shadowBlur = 18;
+  ctx.shadowColor = accent;
+
+  for (const note of notes) {
+    const x = (note.start_seconds / totalDuration) * width;
+    const noteWidth = Math.max(
+      8,
+      (Math.max(0.05, note.duration_seconds) / totalDuration) * width,
+    );
+    const y =
+      height - ((note.pitch - minPitch + 1) / pitchRange) * (height - 24) - 10;
+    const noteHeight = Math.max(10, (height - 34) / pitchRange + 4);
+    roundRect(ctx, x + 2, y, noteWidth, noteHeight, 8, true);
+  }
+
+  ctx.shadowBlur = 0;
+}
+
+function roundRect(ctx, x, y, width, height, radius, fill) {
+  const r = Math.min(radius, width / 2, height / 2);
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.arcTo(x + width, y, x + width, y + height, r);
+  ctx.arcTo(x + width, y + height, x, y + height, r);
+  ctx.arcTo(x, y + height, x, y, r);
+  ctx.arcTo(x, y, x + width, y, r);
+  ctx.closePath();
+  if (fill) {
+    ctx.fill();
+  }
+}
+
+function eventsToNotes(events) {
+  const notes = [];
+  const pending = new Map();
+  let currentTime = 0;
+
+  for (const event of events) {
+    currentTime += event.delta_seconds;
+    const key = `${event.channel}:${event.note}`;
+
+    if (event.type === "note_on" && event.velocity > 0) {
+      const stack = pending.get(key) || [];
+      stack.push({
+        note: event.note,
+        velocity: event.velocity,
+        start_seconds: currentTime,
+      });
+      pending.set(key, stack);
+      continue;
+    }
+
+    const stack = pending.get(key);
+    if (!stack?.length) {
+      continue;
+    }
+
+    const noteOn = stack.shift();
+    notes.push({
+      pitch: noteOn.note,
+      velocity: noteOn.velocity,
+      start_seconds: roundNumber(noteOn.start_seconds),
+      duration_seconds: roundNumber(Math.max(0, currentTime - noteOn.start_seconds)),
+      end_seconds: roundNumber(currentTime),
+    });
+    if (!stack.length) {
+      pending.delete(key);
+    }
+  }
+
+  notes.sort(
+    (left, right) =>
+      left.start_seconds - right.start_seconds || left.pitch - right.pitch,
+  );
+  return notes;
+}
+
+async function createSession() {
+  const settings = readSessionSettingsFromControls();
+  const response = await fetch("/api/session", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(settings),
+  });
+
+  if (!response.ok) {
+    throw new Error(await response.text());
+  }
+
+  const payload = await response.json();
+  state.sessionId = payload.session_id;
+  state.sessionConfiguration = payload.configuration;
+  elements.sessionId.textContent = payload.session_id;
+  syncSettingsControls(payload.configuration);
+  updateSessionActionState();
+  setSessionStatus("Ready");
+  setPhraseMessage(
+    `Session created. ${describeSessionSettings(payload.configuration).join(" · ")}.`,
+  );
+  await refreshSessionActivity();
+}
+
+async function ensureSession() {
+  if (!state.sessionId) {
+    await createSession();
+  }
+}
+
+async function resetSession() {
+  if (!state.sessionId) {
+    setPhraseMessage("Create a session before resetting it.", true);
+    return;
+  }
+
+  const response = await fetch(`/api/sessions/${state.sessionId}/reset`, {
+    method: "POST",
+  });
+  if (!response.ok) {
+    throw new Error(await response.text());
+  }
+  const payload = await response.json();
+
+  state.lastGeneratedPhrase = null;
+  renderGeneratedStats(null);
+  syncSettingsControls(payload.configuration);
+  setPhraseMessage("Session memory cleared and the current settings were preserved.");
+  await refreshMemory();
+}
+
+async function applyCurrentSessionSettings() {
+  if (!state.sessionId) {
+    setPhraseMessage("Create a session before applying settings.", true);
+    return;
+  }
+
+  const settings = readSessionSettingsFromControls();
+  const response = await fetch(`/api/sessions/${state.sessionId}/settings`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(settings),
+  });
+
+  if (!response.ok) {
+    throw new Error(await response.text());
+  }
+
+  const payload = await response.json();
+  syncSettingsControls(payload.configuration);
+  setPhraseMessage(
+    `Session settings updated. ${describeSessionSettings(payload.configuration).join(" · ")}.`,
+  );
+  await refreshMemory();
+}
+
+async function refreshHistory() {
+  if (!state.sessionId) {
+    return;
+  }
+
+  const response = await fetch(
+    `/api/sessions/${state.sessionId}/history?limit=10`,
+  );
+  if (!response.ok) {
+    throw new Error(await response.text());
+  }
+
+  const payload = await response.json();
+  renderHistory(payload.items);
+}
+
+async function refreshMemory() {
+  if (!state.sessionId) {
+    return;
+  }
+
+  const response = await fetch(`/api/sessions/${state.sessionId}/memory`);
+  if (!response.ok) {
+    throw new Error(await response.text());
+  }
+
+  const payload = await response.json();
+  renderMemory(payload);
+}
+
+async function refreshSessionActivity() {
+  if (!state.sessionId) {
+    return;
+  }
+
+  await Promise.all([refreshHistory(), refreshMemory()]);
+}
+
+async function sendCurrentPhrase() {
+  if (!state.lastCapturedPhrase.length) {
+    setPhraseMessage("No completed phrase is ready yet.", true);
+    return;
+  }
+
+  await ensureSession();
+  setPhraseStatus("Sending");
+
+  const response = await fetch("/api/continue", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      session_id: state.sessionId,
+      phrase: state.lastCapturedPhrase,
+      learn_input: elements.learnInputToggle.checked,
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(errorText);
+  }
+
+  const payload = await response.json();
+  state.lastGeneratedPhrase = payload.generated_phrase;
+  renderGeneratedStats(payload.generated_phrase);
+  setPhraseStatus(payload.generated_phrase.note_count ? "Generated" : "Primed");
+  setPhraseMessage(
+    payload.status_message ||
+      `Continuation generated: ${payload.generated_phrase.note_count} notes returned.`,
+  );
+  await refreshSessionActivity();
+  if (payload.generated_phrase.event_count > 0) {
+    await playPayload(payload.generated_phrase);
+  }
+}
+
+async function checkServer() {
+  const response = await fetch("/health");
+  if (!response.ok) {
+    throw new Error("Server health check failed.");
+  }
+  const payload = await response.json();
+  elements.serverStatus.textContent = payload.ok
+    ? payload.seeded
+      ? "Healthy / seeded"
+      : "Healthy / empty memory"
+    : "Unavailable";
+}
+
+function selectedMidiOutput() {
+  if (!state.midiAccess) {
+    return null;
+  }
+  return state.midiAccess.outputs.get(elements.midiOutputSelect.value) || null;
+}
+
+async function playPayload(payload) {
+  if (!payload?.events?.length) {
+    return;
+  }
+
+  if (elements.midiOutputSelect.value === BROWSER_SYNTH_ID) {
+    await synth.play(payload.events);
+    return;
+  }
+
+  const output = selectedMidiOutput();
+  if (!output) {
+    await synth.play(payload.events);
+    return;
+  }
+
+  await output.open();
+  let cursorMs = 0;
+  const startAt = window.performance.now() + 80;
+  for (const event of payload.events) {
+    cursorMs += event.delta_seconds * 1000;
+    const status =
+      event.type === "note_on" && event.velocity > 0
+        ? 0x90 | (event.channel & 0x0f)
+        : 0x80 | (event.channel & 0x0f);
+    output.send([status, event.note, event.velocity], startAt + cursorMs);
+  }
+}
+
+async function populateMidiSelectors() {
+  if (!state.midiAccess) {
+    return;
+  }
+
+  const inputs = [...state.midiAccess.inputs.values()];
+  const outputs = [...state.midiAccess.outputs.values()];
+  const previousInputId = elements.midiInputSelect.value;
+  const previousOutputId = elements.midiOutputSelect.value;
+
+  elements.midiInputSelect.disabled = false;
+  elements.midiInputSelect.innerHTML = inputs.length
+    ? inputs
+        .map(
+          (input) =>
+            `<option value="${input.id}">${input.name || input.id}</option>`,
+        )
+        .join("")
+    : `<option value="">No MIDI inputs found</option>`;
+
+  elements.midiOutputSelect.disabled = false;
+  const outputOptions = [
+    `<option value="${BROWSER_SYNTH_ID}">Browser Synth</option>`,
+    ...outputs.map(
+      (output) =>
+        `<option value="${output.id}">${output.name || output.id}</option>`,
+    ),
+  ];
+  elements.midiOutputSelect.innerHTML = outputOptions.join("");
+  elements.midiOutputSelect.value =
+    previousOutputId &&
+    (previousOutputId === BROWSER_SYNTH_ID ||
+      state.midiAccess.outputs.has(previousOutputId))
+      ? previousOutputId
+      : BROWSER_SYNTH_ID;
+  updateSelectedOutput();
+
+  if (inputs.length) {
+    const inputId = state.midiAccess.inputs.has(previousInputId)
+      ? previousInputId
+      : inputs[0].id;
+    await attachInput(inputId);
+  } else {
+    detachCurrentInput();
+    setSelectedInputName("No MIDI input found");
+    setMidiStatus("No inputs");
+    setLastMidiEvent("None yet");
+  }
+}
+
+function detachCurrentInput() {
+  if (!state.midiAccess || !state.activeInputId) {
+    return;
+  }
+  const current = state.midiAccess.inputs.get(state.activeInputId);
+  if (current) {
+    current.onmidimessage = null;
+    void current.close().catch(() => {});
+  }
+  state.activeInputId = null;
+}
+
+async function attachInput(inputId) {
+  detachCurrentInput();
+
+  if (!state.midiAccess || !inputId) {
+    state.activeInputId = null;
+    setSelectedInputName("No MIDI input selected");
+    return;
+  }
+
+  const input = state.midiAccess.inputs.get(inputId);
+  if (!input) {
+    setSelectedInputName("Selected input is unavailable");
+    return;
+  }
+
+  await input.open();
+  input.onmidimessage = (messageEvent) => {
+    recorder.handleMessage(messageEvent);
+    const [statusByte, note, velocity = 0] = [...messageEvent.data];
+    const status = statusByte & 0xf0;
+    const type =
+      status === 0x90 && velocity > 0
+        ? "note_on"
+        : status === 0x80 || (status === 0x90 && velocity === 0)
+          ? "note_off"
+          : "message";
+    setLastMidiEvent(`${type} ${note} v${velocity}`);
+    setPhraseMessage(
+      `Receiving MIDI from ${input.name || input.id}. Waiting for phrase end…`,
+    );
+  };
+
+  state.activeInputId = inputId;
+  elements.midiInputSelect.value = inputId;
+  setSelectedInputName(input.name || input.id);
+  setMidiStatus(`Listening on ${input.name || input.id}`);
+}
+
+async function connectMidi() {
+  if (!navigator.requestMIDIAccess) {
+    throw new Error("This browser does not support the Web MIDI API.");
+  }
+
+  state.midiAccess = await navigator.requestMIDIAccess({ sysex: false });
+  state.midiAccess.onstatechange = () => {
+    void populateMidiSelectors();
+  };
+  await populateMidiSelectors();
+  if (!state.activeInputId) {
+    setMidiStatus("Connected / choose input");
+  }
+  setPhraseStatus("Listening");
+}
+
+function updateSelectedOutput() {
+  const outputId = elements.midiOutputSelect.value;
+  if (outputId === BROWSER_SYNTH_ID) {
+    setSelectedOutputName("Browser Synth");
+    return;
+  }
+
+  const output = selectedMidiOutput();
+  setSelectedOutputName(output ? output.name || output.id : "Unavailable output");
+}
+
+function clearPhrases() {
+  state.lastCapturedPhrase = [];
+  state.lastGeneratedPhrase = null;
+  recorder.reset();
+  renderCapturedStats([], [], false);
+  renderGeneratedStats(null);
+  setPhraseStatus("Waiting for MIDI");
+  setPhraseMessage("Cleared the local phrase buffers.");
+}
+
+function bindEvents() {
+  elements.viewTabs.forEach((node) => {
+    node.addEventListener("click", () => {
+      setActivityView(node.dataset.viewTab);
+    });
+  });
+
+  elements.createSessionButton.addEventListener("click", async () => {
+    try {
+      await createSession();
+    } catch (error) {
+      setPhraseMessage(error.message, true);
+    }
+  });
+
+  elements.resetSessionButton.addEventListener("click", async () => {
+    try {
+      await resetSession();
+    } catch (error) {
+      setPhraseMessage(error.message, true);
+    }
+  });
+
+  elements.connectMidiButton.addEventListener("click", async () => {
+    try {
+      await connectMidi();
+    } catch (error) {
+      setPhraseMessage(error.message, true);
+      setMidiStatus("Unavailable");
+    }
+  });
+
+  elements.refreshMidiButton.addEventListener("click", async () => {
+    try {
+      if (!state.midiAccess) {
+        await connectMidi();
+        return;
+      }
+      await populateMidiSelectors();
+      setPhraseMessage("MIDI ports refreshed.");
+    } catch (error) {
+      setPhraseMessage(error.message, true);
+    }
+  });
+
+  elements.sendPhraseButton.addEventListener("click", async () => {
+    try {
+      await sendCurrentPhrase();
+    } catch (error) {
+      setPhraseMessage(error.message, true);
+      setPhraseStatus("Error");
+    }
+  });
+
+  elements.replayGeneratedButton.addEventListener("click", async () => {
+    if (!state.lastGeneratedPhrase) {
+      setPhraseMessage("No generated phrase is available yet.", true);
+      return;
+    }
+    try {
+      await playPayload(state.lastGeneratedPhrase);
+      setPhraseMessage("Replaying the latest generated phrase.");
+    } catch (error) {
+      setPhraseMessage(error.message, true);
+    }
+  });
+
+  elements.clearPhraseButton.addEventListener("click", () => {
+    clearPhrases();
+  });
+
+  elements.applySettingsButton.addEventListener("click", async () => {
+    try {
+      await applyCurrentSessionSettings();
+    } catch (error) {
+      setPhraseMessage(error.message, true);
+    }
+  });
+
+  elements.midiInputSelect.addEventListener("change", async (event) => {
+    try {
+      await attachInput(event.target.value);
+      setPhraseMessage(`MIDI input changed to ${elements.selectedInputName.textContent}.`);
+    } catch (error) {
+      setPhraseMessage(error.message, true);
+    }
+  });
+
+  elements.midiOutputSelect.addEventListener("change", async () => {
+    updateSelectedOutput();
+    const output = selectedMidiOutput();
+    if (output) {
+      try {
+        await output.open();
+      } catch (error) {
+        setPhraseMessage(error.message, true);
+        return;
+      }
+    }
+    setPhraseMessage(`Playback output set to ${elements.selectedOutputName.textContent}.`);
+  });
+
+  elements.learnInputToggle.addEventListener("change", () => {
+    renderSessionSettingsSummary();
+  });
+
+  elements.transposeToggle.addEventListener("change", () => {
+    renderSessionSettingsSummary();
+  });
+
+  elements.forgetToggle.addEventListener("change", () => {
+    updateKeepLastFieldState();
+    renderSessionSettingsSummary();
+  });
+
+  elements.keepLastInput.addEventListener("change", () => {
+    elements.keepLastInput.value = String(
+      normalizedKeepLastInputs(elements.keepLastInput.value),
+    );
+    renderSessionSettingsSummary();
+  });
+
+  elements.decayModeSelect.addEventListener("change", () => {
+    renderSessionSettingsSummary();
+  });
+
+  window.addEventListener("resize", () => {
+    drawPianoRoll(
+      elements.inputRoll,
+      eventsToNotes(state.lastCapturedPhrase),
+      "#6dd3ce",
+      "Input phrase",
+    );
+    renderGeneratedStats(state.lastGeneratedPhrase);
+  });
+}
+
+async function initialize() {
+  bindEvents();
+  clearPhrases();
+  renderMemory(null);
+  setActivityView("history");
+  setSelectedInputName("No MIDI input selected");
+  setSelectedOutputName("Browser Synth");
+  setLastMidiEvent("None yet");
+  updateKeepLastFieldState();
+  renderSessionSettingsSummary();
+  updateSessionActionState();
+  try {
+    await checkServer();
+  } catch (error) {
+    elements.serverStatus.textContent = "Offline";
+    setPhraseMessage(error.message, true);
+  }
+}
+
+initialize();

frontend/index.html

@@ -0,0 +1,262 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Continuator Web Pilot</title>
+    <link rel="stylesheet" href="/assets/styles.css" />
+  </head>
+  <body>
+    <div class="page-aura"></div>
+    <div class="page-grid"></div>
+    <header class="hero">
+      <div class="hero-copy">
+        <p class="eyebrow">Web MIDI + FastAPI + Continuator</p>
+        <h1>Continuator Web Pilot</h1>
+        <p class="lede">
+          Capture a phrase from a MIDI keyboard in the browser, send it to the
+          Python Continuator, and play the continuation back through a MIDI port
+          or a built-in browser synth.
+        </p>
+      </div>
+      <div class="hero-chip">
+        <span>Session-isolated</span>
+        <span>SQLite logged</span>
+        <span>Docker ready</span>
+      </div>
+    </header>
+
+    <main class="layout">
+      <section class="column">
+        <article class="card">
+          <div class="card-head">
+            <h2>Session</h2>
+            <span class="status-pill" id="session-status">No session</span>
+          </div>
+          <p class="muted">
+            Each session owns its own in-memory Continuator engine so users do
+            not share style memory.
+          </p>
+          <div class="button-row">
+            <button id="create-session-button">Create Session</button>
+            <button id="reset-session-button" class="ghost">Reset Memory</button>
+          </div>
+          <div class="settings-compact">
+            <div class="settings-label-row">
+              <span class="small-copy">Continuator settings</span>
+              <span class="small-copy">Compact summary</span>
+            </div>
+            <div id="settings-summary" class="settings-summary"></div>
+          </div>
+          <details class="settings-panel">
+            <summary>Advanced Continuator Settings</summary>
+            <p class="muted settings-copy">
+              Keep the performance controls on the surface, and put the
+              lower-frequency model and memory settings here.
+            </p>
+            <div class="settings-grid">
+              <label class="toggle settings-toggle">
+                <input id="transpose-toggle" type="checkbox" />
+                <span>Transpose incoming phrases before learning</span>
+              </label>
+              <div class="field">
+                <label for="decay-mode-select">Decay mode</label>
+                <select id="decay-mode-select">
+                  <option value="full">Full</option>
+                  <option value="late">Late</option>
+                  <option value="middle">Middle</option>
+                  <option value="early">Early</option>
+                </select>
+              </div>
+              <label class="toggle settings-toggle">
+                <input id="forget-toggle" type="checkbox" />
+                <span>Forget old phrases and keep a rolling memory</span>
+              </label>
+              <div class="field">
+                <label for="keep-last-input">Keep only N last inputs</label>
+                <input id="keep-last-input" type="number" min="1" max="500" step="1" value="20" />
+                <p class="field-hint">
+                  This cap is used when forgetting is enabled.
+                </p>
+              </div>
+            </div>
+            <div class="button-row">
+              <button id="apply-settings-button" class="ghost">
+                Apply to Current Session
+              </button>
+            </div>
+            <p class="small-copy settings-copy">
+              New sessions use these settings automatically. Use Apply to update
+              the current running session without clearing its memory.
+            </p>
+          </details>
+          <dl class="info-grid">
+            <div>
+              <dt>Session ID</dt>
+              <dd id="session-id">Not created yet</dd>
+            </div>
+            <div>
+              <dt>Server</dt>
+              <dd id="server-status">Checking…</dd>
+            </div>
+          </dl>
+        </article>
+
+        <article class="card accent-card">
+          <div class="card-head">
+            <h2>MIDI I/O</h2>
+            <span class="status-pill" id="midi-status">Disconnected</span>
+          </div>
+          <p class="muted">
+            Connect browser MIDI, choose an input and output port explicitly,
+            then play. A phrase is considered finished 1 second after the final
+            note release.
+          </p>
+          <div class="button-row">
+            <button id="connect-midi-button">Connect MIDI</button>
+            <button id="refresh-midi-button" class="ghost">Refresh Ports</button>
+            <label class="toggle">
+              <input id="auto-send-toggle" type="checkbox" checked />
+              <span>Auto-send phrase</span>
+            </label>
+          </div>
+          <div class="field">
+            <label for="midi-input-select">MIDI Input</label>
+            <select id="midi-input-select" disabled>
+              <option>Connect MIDI first</option>
+            </select>
+          </div>
+          <div class="field">
+            <label for="midi-output-select">Playback Output</label>
+            <select id="midi-output-select" disabled>
+              <option>Browser Synth</option>
+            </select>
+          </div>
+          <label class="toggle">
+            <input id="learn-input-toggle" type="checkbox" checked />
+            <span>Learn the played phrase before generating</span>
+          </label>
+          <dl class="info-grid">
+            <div>
+              <dt>Selected Input</dt>
+              <dd id="selected-input-name">None</dd>
+            </div>
+            <div>
+              <dt>Selected Output</dt>
+              <dd id="selected-output-name">Browser Synth</dd>
+            </div>
+            <div>
+              <dt>Last MIDI Event</dt>
+              <dd id="last-midi-event">None yet</dd>
+            </div>
+            <div>
+              <dt>Capture Rule</dt>
+              <dd>1 second after final note-off</dd>
+            </div>
+          </dl>
+        </article>
+
+        <article class="card">
+          <div class="card-head">
+            <h2>Phrase Flow</h2>
+            <span class="status-pill" id="phrase-status">Waiting for MIDI</span>
+          </div>
+          <div class="button-row">
+            <button id="send-phrase-button">Send Phrase</button>
+            <button id="replay-generated-button" class="ghost">Replay Output</button>
+            <button id="clear-phrase-button" class="ghost">Clear</button>
+          </div>
+          <dl class="info-grid">
+            <div>
+              <dt>Captured Events</dt>
+              <dd id="captured-event-count">0</dd>
+            </div>
+            <div>
+              <dt>Captured Notes</dt>
+              <dd id="captured-note-count">0</dd>
+            </div>
+            <div>
+              <dt>Generated Events</dt>
+              <dd id="generated-event-count">0</dd>
+            </div>
+            <div>
+              <dt>Generated Notes</dt>
+              <dd id="generated-note-count">0</dd>
+            </div>
+          </dl>
+          <div class="message-box" id="message-box">
+            Play a short phrase on the selected MIDI input to capture it.
+          </div>
+        </article>
+      </section>
+
+      <section class="column wide-column">
+        <article class="card roll-card">
+          <div class="card-head">
+            <h2>Captured Phrase</h2>
+            <span class="small-copy">Detected from browser MIDI events</span>
+          </div>
+          <canvas id="input-roll" class="piano-roll"></canvas>
+        </article>
+
+        <article class="card roll-card output-card">
+          <div class="card-head">
+            <h2>Generated Continuation</h2>
+            <span class="small-copy">Returned by the Python Continuator engine</span>
+          </div>
+          <canvas id="output-roll" class="piano-roll"></canvas>
+        </article>
+
+        <article class="card">
+          <div class="card-head">
+            <h2>Session Activity</h2>
+            <span class="small-copy">History log and active Continuator memory</span>
+          </div>
+          <div class="view-tabs" role="tablist" aria-label="Session activity views">
+            <button
+              id="history-tab"
+              class="view-tab is-active"
+              data-view-tab="history"
+              type="button"
+              role="tab"
+              aria-selected="true"
+              aria-controls="history-panel"
+            >
+              History
+            </button>
+            <button
+              id="memory-tab"
+              class="view-tab"
+              data-view-tab="memory"
+              type="button"
+              role="tab"
+              aria-selected="false"
+              aria-controls="memory-panel"
+            >
+              Memory
+            </button>
+          </div>
+          <section id="history-panel" class="view-panel" role="tabpanel">
+            <div id="history-list" class="history-list">
+              <p class="muted">Create a session to start building history.</p>
+            </div>
+          </section>
+          <section id="memory-panel" class="view-panel" role="tabpanel" hidden>
+            <div id="memory-summary" class="settings-summary">
+              <span class="settings-chip">No active memory yet</span>
+            </div>
+            <p id="memory-hint" class="small-copy memory-hint">
+              Create a session and play a phrase to inspect the active Continuator memory.
+            </p>
+            <div id="memory-ribbon" class="memory-ribbon"></div>
+            <div id="memory-list" class="history-list">
+              <p class="muted">No active memory to show yet.</p>
+            </div>
+          </section>
+        </article>
+      </section>
+    </main>
+
+    <script type="module" src="/assets/app.js"></script>
+  </body>
+</html>

frontend/styles.css

@@ -0,0 +1,586 @@
+:root {
+  --bg: #071217;
+  --panel: rgba(7, 18, 23, 0.76);
+  --panel-strong: rgba(10, 24, 30, 0.9);
+  --border: rgba(181, 215, 207, 0.14);
+  --text: #ecf4ef;
+  --muted: #9bb8b1;
+  --accent: #f4a261;
+  --accent-soft: rgba(244, 162, 97, 0.18);
+  --secondary: #6dd3ce;
+  --secondary-soft: rgba(109, 211, 206, 0.16);
+  --danger: #ff8e72;
+  --shadow: 0 24px 70px rgba(0, 0, 0, 0.35);
+  --radius: 24px;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  min-height: 100%;
+}
+
+body {
+  position: relative;
+  overflow-x: hidden;
+  background:
+    radial-gradient(circle at top left, rgba(109, 211, 206, 0.18), transparent 34%),
+    radial-gradient(circle at top right, rgba(244, 162, 97, 0.16), transparent 28%),
+    linear-gradient(180deg, #071217 0%, #0d1f27 50%, #081118 100%);
+  color: var(--text);
+  font-family: "Avenir Next", "Segoe UI Variable", "Trebuchet MS", sans-serif;
+}
+
+.page-aura,
+.page-grid {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+}
+
+.page-aura {
+  background:
+    radial-gradient(circle at 18% 12%, rgba(255, 255, 255, 0.07), transparent 18%),
+    radial-gradient(circle at 82% 8%, rgba(255, 255, 255, 0.05), transparent 14%);
+  opacity: 0.85;
+}
+
+.page-grid {
+  background-image:
+    linear-gradient(rgba(255, 255, 255, 0.03) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.03) 1px, transparent 1px);
+  background-size: 56px 56px;
+  mask-image: linear-gradient(180deg, rgba(0, 0, 0, 0.55), transparent 85%);
+}
+
+.hero,
+.layout {
+  position: relative;
+  z-index: 1;
+}
+
+.hero {
+  display: grid;
+  grid-template-columns: minmax(0, 1.4fr) minmax(260px, 0.8fr);
+  gap: 24px;
+  align-items: end;
+  padding: 56px 28px 24px;
+  animation: rise-in 700ms ease;
+}
+
+.hero-copy h1 {
+  margin: 8px 0 14px;
+  font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;
+  font-size: clamp(2.4rem, 5vw, 4.4rem);
+  line-height: 0.95;
+  letter-spacing: -0.03em;
+}
+
+.eyebrow {
+  margin: 0;
+  color: var(--secondary);
+  font-size: 0.82rem;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+}
+
+.lede {
+  margin: 0;
+  max-width: 60ch;
+  color: var(--muted);
+  font-size: 1.05rem;
+  line-height: 1.65;
+}
+
+.hero-chip {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  justify-content: flex-end;
+}
+
+.hero-chip span {
+  padding: 10px 14px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: rgba(6, 15, 19, 0.58);
+  backdrop-filter: blur(10px);
+  color: var(--muted);
+  font-size: 0.92rem;
+}
+
+.layout {
+  display: grid;
+  grid-template-columns: minmax(300px, 0.92fr) minmax(0, 1.28fr);
+  gap: 22px;
+  padding: 0 28px 32px;
+}
+
+.column {
+  display: flex;
+  flex-direction: column;
+  gap: 22px;
+}
+
+.wide-column {
+  min-width: 0;
+}
+
+.card {
+  position: relative;
+  overflow: hidden;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--panel);
+  backdrop-filter: blur(18px);
+  box-shadow: var(--shadow);
+  padding: 22px;
+  animation: rise-in 700ms ease;
+}
+
+.card::before {
+  content: "";
+  position: absolute;
+  inset: 0 0 auto;
+  height: 1px;
+  background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.34), transparent);
+}
+
+.accent-card {
+  background:
+    linear-gradient(135deg, rgba(109, 211, 206, 0.08), transparent 50%),
+    var(--panel-strong);
+}
+
+.output-card {
+  background:
+    linear-gradient(135deg, rgba(244, 162, 97, 0.08), transparent 55%),
+    var(--panel-strong);
+}
+
+.card-head {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 14px;
+}
+
+.card-head h2 {
+  margin: 0;
+  font-size: 1.18rem;
+}
+
+.small-copy,
+.muted {
+  color: var(--muted);
+}
+
+.muted {
+  margin: 0 0 18px;
+  line-height: 1.55;
+}
+
+.button-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-bottom: 18px;
+}
+
+button,
+select,
+input {
+  font: inherit;
+}
+
+button {
+  cursor: pointer;
+  border: 0;
+  border-radius: 999px;
+  background: linear-gradient(135deg, #f4a261, #ef7f58);
+  color: #081118;
+  font-weight: 700;
+  padding: 11px 16px;
+  transition: transform 160ms ease, box-shadow 160ms ease, opacity 160ms ease;
+  box-shadow: 0 12px 30px rgba(239, 127, 88, 0.22);
+}
+
+button:hover:not(:disabled) {
+  transform: translateY(-1px);
+}
+
+button:disabled {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+button.ghost {
+  background: rgba(255, 255, 255, 0.06);
+  color: var(--text);
+  box-shadow: none;
+  border: 1px solid var(--border);
+}
+
+.view-tabs {
+  display: inline-flex;
+  gap: 8px;
+  padding: 6px;
+  margin-bottom: 18px;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.04);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.view-tab {
+  border: 1px solid transparent;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--muted);
+  box-shadow: none;
+  padding: 9px 14px;
+}
+
+.view-tab.is-active {
+  background: linear-gradient(135deg, rgba(244, 162, 97, 0.24), rgba(109, 211, 206, 0.16));
+  border-color: rgba(255, 255, 255, 0.08);
+  color: var(--text);
+}
+
+.view-panel[hidden] {
+  display: none;
+}
+
+.status-pill {
+  border-radius: 999px;
+  padding: 8px 12px;
+  background: rgba(255, 255, 255, 0.05);
+  color: var(--muted);
+  font-size: 0.88rem;
+}
+
+.field {
+  display: grid;
+  gap: 8px;
+  margin-bottom: 14px;
+}
+
+.field label,
+.toggle {
+  font-size: 0.95rem;
+}
+
+select {
+  width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  background: rgba(255, 255, 255, 0.05);
+  color: var(--text);
+  padding: 12px 14px;
+}
+
+input[type="number"] {
+  width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  background: rgba(255, 255, 255, 0.05);
+  color: var(--text);
+  padding: 12px 14px;
+}
+
+input[type="number"]:disabled {
+  opacity: 0.55;
+}
+
+.toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  color: var(--muted);
+}
+
+.toggle input {
+  accent-color: var(--accent);
+}
+
+.settings-compact {
+  margin-bottom: 18px;
+}
+
+.settings-label-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 10px;
+}
+
+.settings-summary {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+.settings-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 9px 12px;
+  border-radius: 999px;
+  border: 1px solid rgba(255, 255, 255, 0.07);
+  background: rgba(255, 255, 255, 0.04);
+  color: var(--muted);
+  font-size: 0.88rem;
+}
+
+.settings-panel {
+  margin-bottom: 18px;
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  border-radius: 20px;
+  background: rgba(255, 255, 255, 0.03);
+  overflow: hidden;
+}
+
+.settings-panel summary {
+  cursor: pointer;
+  list-style: none;
+  padding: 16px 18px;
+  font-weight: 700;
+}
+
+.settings-panel summary::-webkit-details-marker {
+  display: none;
+}
+
+.settings-panel[open] summary {
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.settings-panel > :not(summary) {
+  margin-left: 18px;
+  margin-right: 18px;
+}
+
+.settings-copy {
+  margin-top: 14px;
+}
+
+.settings-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.settings-toggle {
+  min-height: 54px;
+  padding: 14px 16px;
+  border-radius: 18px;
+  background: rgba(255, 255, 255, 0.04);
+  border: 1px solid rgba(255, 255, 255, 0.05);
+}
+
+.field-hint {
+  margin: 8px 0 0;
+  color: var(--muted);
+  font-size: 0.84rem;
+  line-height: 1.45;
+}
+
+.info-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+  margin: 0;
+}
+
+.info-grid div {
+  padding: 14px;
+  border-radius: 18px;
+  background: rgba(255, 255, 255, 0.04);
+  border: 1px solid rgba(255, 255, 255, 0.05);
+}
+
+.info-grid dt {
+  color: var(--muted);
+  font-size: 0.82rem;
+  margin-bottom: 6px;
+}
+
+.info-grid dd {
+  margin: 0;
+  word-break: break-word;
+  font-weight: 600;
+}
+
+.message-box {
+  min-height: 64px;
+  border-radius: 18px;
+  padding: 14px;
+  background: linear-gradient(135deg, rgba(109, 211, 206, 0.08), rgba(255, 255, 255, 0.02));
+  border: 1px solid var(--border);
+  color: var(--muted);
+  line-height: 1.55;
+}
+
+.roll-card {
+  padding-bottom: 16px;
+}
+
+.piano-roll {
+  width: 100%;
+  height: 244px;
+  display: block;
+  border-radius: 18px;
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.04), transparent),
+    rgba(255, 255, 255, 0.02);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.history-list {
+  display: grid;
+  gap: 10px;
+}
+
+.memory-hint {
+  margin: 12px 0 14px;
+  line-height: 1.5;
+}
+
+.memory-ribbon {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(28px, 1fr));
+  gap: 8px;
+  margin-bottom: 16px;
+}
+
+.memory-ribbon:empty {
+  display: none;
+}
+
+.memory-ribbon-cell {
+  min-height: 42px;
+  padding: 0;
+  border-radius: 12px;
+  border: 1px solid rgba(255, 255, 255, 0.07);
+  background: rgba(255, 255, 255, 0.04);
+  box-shadow: none;
+}
+
+.memory-ribbon-cell.seed {
+  background: rgba(109, 211, 206, 0.14);
+}
+
+.memory-ribbon-cell.live {
+  background: rgba(244, 162, 97, 0.16);
+}
+
+.memory-item .history-kind {
+  min-width: 96px;
+}
+
+.history-item {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  gap: 14px;
+  align-items: center;
+  width: 100%;
+  text-align: left;
+  box-shadow: none;
+  border-radius: 18px;
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  padding: 14px;
+  background: rgba(255, 255, 255, 0.03);
+  color: var(--text);
+}
+
+.history-item:hover {
+  border-color: rgba(244, 162, 97, 0.28);
+}
+
+.history-kind {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 82px;
+  padding: 8px 10px;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.05);
+  color: var(--muted);
+  font-size: 0.82rem;
+  text-transform: capitalize;
+}
+
+.history-meta {
+  display: grid;
+  gap: 4px;
+}
+
+.history-meta strong {
+  font-size: 0.96rem;
+}
+
+.history-meta span {
+  color: var(--muted);
+  font-size: 0.88rem;
+}
+
+.history-index {
+  color: var(--accent);
+  font-size: 0.85rem;
+}
+
+@keyframes rise-in {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (max-width: 980px) {
+  .hero,
+  .layout {
+    grid-template-columns: 1fr;
+  }
+
+  .hero {
+    padding-top: 40px;
+  }
+
+  .hero-chip {
+    justify-content: flex-start;
+  }
+}
+
+@media (max-width: 640px) {
+  .hero,
+  .layout {
+    padding-left: 16px;
+    padding-right: 16px;
+  }
+
+  .card {
+    padding: 18px;
+  }
+
+  .info-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .settings-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .piano-roll {
+    height: 206px;
+  }
+}