From 4fd8ece170ac02edd1ea9b5552fbd230f0187738 Mon Sep 17 00:00:00 2001
From: Masahiko AMANO <hiko-19@ya.ru>
Date: Wed, 20 May 2026 00:29:52 +0300
Subject: [PATCH] refactor: replace fixed STYLE_user with open-ended style tag
 system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- STYLE_user renamed to STYLE_H1K0 in VOCAB (author's personal tag)
- Style field now accepts any [A-Za-z][A-Za-z0-9_]* identifier in .chord files
- Unknown styles fall back to STYLE_other at tokenization time with a log warning
- Test fixtures updated to style: other; drop closed _VALID_STYLES frozenset
- Spec bumped to v2.1: documents open style field, fallback behaviour, and §5.7
  guide on registering a new style token

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/chord_format_spec.md                 | 59 +++++++++++++++--------
 src/tokenizer.py                          | 19 +++++---
 tests/fixtures/invalid_bar_count.chord    |  2 +-
 tests/fixtures/invalid_chord_symbol.chord |  2 +-
 tests/fixtures/midi_export_test.chord     |  2 +-
 tests/fixtures/valid_b_minor.chord        |  2 +-
 tests/fixtures/valid_c_major.chord        |  2 +-
 tests/fixtures/valid_fsharp_major.chord   |  2 +-
 tests/fixtures/valid_gsharp_minor.chord   |  2 +-
 tests/test_chord_file_parser.py           |  2 +-
 tests/test_dataset.py                     |  2 +-
 tests/test_tokenizer.py                   |  2 +-
 12 files changed, 60 insertions(+), 38 deletions(-)

diff --git a/docs/chord_format_spec.md b/docs/chord_format_spec.md
index 41d43ab..98e3ff1 100644
--- a/docs/chord_format_spec.md
+++ b/docs/chord_format_spec.md
@@ -1,7 +1,7 @@
 # Спецификация формата данных hamori
 
-**Версия:** 2.0
-**Дата:** 2026-05-16
+**Версия:** 2.1
+**Дата:** 2026-05-20
 
 ---
 
@@ -18,7 +18,7 @@
 Формат двухуровневый:
 
 - **Исходный (`.chord`)** — то, что пишется руками. Близок к лид-шиту, человекочитаем, легко правится в любом текстовом редакторе.
-- **Токенизированный** — то, что подаётся в модель. Факторизованное представление с маленьким словарём (~75 токенов).
+- **Токенизированный** — то, что подаётся в модель. Факторизованное представление с фиксированным словарём (81 токен).
 
 Между уровнями стоит детерминированный парсер.
 
@@ -33,7 +33,7 @@
 # key: D_major
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: H1K0
 # function: chorus
 
 | Gmaj7 . . . | A     . . . | F#m7  . . . | Bm7  . . . |
@@ -53,14 +53,14 @@
 
 ### 3.3 Поля шапки
 
-| Поле          | Обязательно | Допустимые значения                                                              | Назначение                                   |
-| ------------- | ----------- | -------------------------------------------------------------------------------- | -------------------------------------------- |
-| `title`       | да          | свободная строка                                                                 | идентификация периода                        |
-| `key`         | да          | `<note>_major` или `<note>_minor`                                                | для нормализации в C/Am перед обучением      |
-| `time`        | да          | `4/4`, `3/4`, `6/8`, `2/4`, `12/8`                                               | тактовый размер                              |
-| `subdivision` | да          | `4` или `8`                                                                      | сколько позиций в одном такте                |
-| `style`       | да          | `user`, `jpop`, `classical`, `jazz`, `other`                                     | стилевой тег периода                         |
-| `function`    | нет         | `verse`, `prechorus`, `chorus`, `bridge`, `intro`, `outro`, `interlude`, `other` | функциональная роль периода в исходной пьесе |
+| Поле          | Обязательно | Допустимые значения                                                              | Назначение                                                                                                                    |
+| ------------- | ----------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | да          | свободная строка                                                                 | идентификация периода                                                                                                         |
+| `key`         | да          | `<note>_major` или `<note>_minor`                                                | для нормализации в C/Am перед обучением                                                                                       |
+| `time`        | да          | `4/4`, `3/4`, `6/8`, `2/4`, `12/8`                                               | тактовый размер                                                                                                               |
+| `subdivision` | да          | `4` или `8`                                                                      | сколько позиций в одном такте                                                                                                 |
+| `style`       | да          | любой идентификатор `[A-Za-z][A-Za-z0-9_]*` (например: `H1K0`, `jpop`, `other`)  | стилевой тег периода; при токенизации тег должен совпасть с токеном `STYLE_<tag>` в словаре, иначе используется `STYLE_other` |
+| `function`    | нет         | `verse`, `prechorus`, `chorus`, `bridge`, `intro`, `outro`, `interlude`, `other` | функциональная роль периода в исходной пьесе                                                                                  |
 
 **Допустимые ноты для `key`:** `C, C#, D, D#, E, F, F#, G, G#, A, A#, B`. Бемольные написания (`Db`, `Eb`, ...) принимаются и нормализуются к диезной форме.
 
@@ -110,10 +110,10 @@
 Примеры:
 
 - `C` → root=C, quality=maj (по умолчанию), без extension, bass=root
-- `Am7` → root=A, quality=min7, без extension, bass=root
+- `Am7` → root=A, quality=m7, без extension, bass=root
 - `Fmaj9` → root=F, quality=maj7, extension=9, bass=root
 - `G7/B` → root=G, quality=7, без extension, bass=B
-- `Dm9/F` → root=D, quality=min7, extension=9, bass=F
+- `Dm9/F` → root=D, quality=m7, extension=9, bass=F
 
 ### 4.2 Корневой тон
 
@@ -228,7 +228,7 @@ D/F#     ← D, бас F♯
 - `MODE_major`, `MODE_minor` — 2 токена (наследие тональности; нужны, потому что мажор и минор остаются разделёнными)
 - `TIME_4/4`, `TIME_3/4`, `TIME_6/8`, `TIME_2/4`, `TIME_12/8` — 5 токенов
 - `SUB_4`, `SUB_8` — 2 токена
-- `STYLE_user`, `STYLE_jpop`, `STYLE_classical`, `STYLE_jazz`, `STYLE_other` — 5 токенов
+- `STYLE_H1K0`, `STYLE_jpop`, `STYLE_classical`, `STYLE_jazz`, `STYLE_other` — 5 токенов стиля (текущий словарь); неизвестный тег → `STYLE_other`
 - `FUNC_verse`, `FUNC_prechorus`, `FUNC_chorus`, `FUNC_bridge`, `FUNC_intro`, `FUNC_outro`, `FUNC_interlude`, `FUNC_other`, `FUNC_unspecified` — 9 токенов
 
 **Аккордовые слоты (новый аккорд = ровно 4 токена в порядке root, quality, extension, bass):**
@@ -274,7 +274,7 @@ BAR
 1. Прочитать шапку.
 2. Транспонировать все аккорды: если `key = X_major`, транспонировать так, чтобы X стало C; если `key = X_minor` — так, чтобы X стало A.
 3. Выпустить `<BOS>`.
-4. Выпустить метатокены: `MODE_<major|minor>`, `TIME_<x>`, `SUB_<x>`, `STYLE_<x>`, `FUNC_<x>` (если `function` не задан — выпустить `FUNC_unspecified`).
+4. Выпустить метатокены: `MODE_<major|minor>`, `TIME_<x>`, `SUB_<x>`, `STYLE_<x>`, `FUNC_<x>` (если `function` не задан — выпустить `FUNC_unspecified`; если `STYLE_<style>` отсутствует в словаре — выпустить `STYLE_other` с предупреждением в лог).
 5. Для каждого такта:
    - Для каждой позиции в такте:
      - Если новый аккорд: разобрать на (root, quality, extension, bass), выпустить 4 токена в этом порядке.
@@ -304,6 +304,18 @@ BAR
 
 Длинный период (16 тактов с частой сменой): редко превышает 250 токенов. Контекстное окно 512 токенов более чем достаточно.
 
+### 5.7 Добавление нового стилевого тега
+
+Поле `style` в `.chord` файле принимает любой идентификатор — дополнительный код менять не нужно. Однако, чтобы модель кондиционировалась на новый стиль отдельным токеном (а не сваливала его в `STYLE_other`), нужно зарегистрировать токен в словаре:
+
+1. Открыть `src/tokenizer.py`, найти блок `# Style (5)` в списке `VOCAB`.
+2. Добавить `"STYLE_<tag>"` в этот блок. Пример: `"STYLE_ALICE"`.
+3. Обновить счётчик в §5.2 этой спецификации и в итоговой строке («**N токенов**»).
+4. **Переобучить модель с нуля** — изменение размера словаря меняет размер матрицы эмбеддингов и выходного слоя; дообучить существующий чекпоинт не получится.
+5. Обновить все `.chord` файлы нужного корпуса, выставив новый тег в поле `style`.
+
+Если токен не зарегистрирован, парсер принимает файл без ошибок, но токенизатор выдаёт `STYLE_other` и пишет предупреждение в лог. Это удобно для экспериментов до переобучения.
+
 ---
 
 ## 6. Полный пример
@@ -315,10 +327,10 @@ BAR
 # key: G_major
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: H1K0
 # function: chorus
 
-| Gmaj7 . . .   | Bm7  . . .  | Em7 . . . | C    . . D . |
+| Gmaj7 . . . | Bm7  . . . | Em7 . . . | C . D . |
 | Cmaj7 . . .   | G/B  . . .  | Am7 . D .  | G    . . . |
 ```
 
@@ -327,7 +339,7 @@ BAR
 Шаг 1: транспонировать из G major в C major (вниз на 7 полутонов или вверх на 5):
 
 ```
-| Cmaj7 . . . | Em7 . . . | Am7 . . . | F . . G . |
+| Cmaj7 . . . | Em7 . . . | Am7 . . . | F . G . |
 | Fmaj7 . . . | C/E . . . | Dm7 . G .  | C . . . |
 ```
 
@@ -335,7 +347,7 @@ BAR
 
 ```
 <BOS>
-MODE_major  TIME_4/4  SUB_4  STYLE_user  FUNC_chorus
+MODE_major  TIME_4/4  SUB_4  STYLE_H1K0  FUNC_chorus
 
 ROOT_C  QUAL_maj7  EXT_none  BASS_root
 HOLD  HOLD  HOLD
@@ -468,7 +480,12 @@ YYYY_NNN_<short-title>_<function>.chord
 
 ## 11. История изменений
 
-- **v2.0** (текущая)
+- **v2.1** (текущая)
+  - Поле `style` теперь принимает любой идентификатор `[A-Za-z][A-Za-z0-9_]*`, а не фиксированный список.
+  - `STYLE_user` заменён на `STYLE_H1K0` (авторский тег) в словаре модели.
+  - Неизвестный стиль при токенизации маппируется на `STYLE_other` с предупреждением в лог.
+
+- **v2.0**
   - Единицей датасета стал **гармонический период**, не пьеса целиком.
   - Введена **нормализация тональности** в C major / A minor. Поле `key` сохраняется в шапке для парсера, но в словаре модели нет — есть только `MODE_major` / `MODE_minor`.
   - Введён тег `function` (необязательный) как метаданные периода.
diff --git a/src/tokenizer.py b/src/tokenizer.py
index 1d7da3e..e410ccf 100644
--- a/src/tokenizer.py
+++ b/src/tokenizer.py
@@ -17,6 +17,7 @@ See docs/chord_format_spec.md §5.2 for the vocabulary specification.
 from __future__ import annotations
 
 import logging
+import re
 from dataclasses import dataclass, replace
 from pathlib import Path
 
@@ -67,9 +68,6 @@ _FLAT_TO_SHARP: dict[str, str] = {
 }
 
 _VALID_TIMES: frozenset[str] = frozenset({"4/4", "3/4", "6/8", "2/4", "12/8"})
-_VALID_STYLES: frozenset[str] = frozenset(
-    {"user", "jpop", "classical", "jazz", "other"}
-)
 _VALID_FUNCTIONS: frozenset[str] = frozenset({
     "verse", "prechorus", "chorus", "bridge",
     "intro", "outro", "interlude", "other",
@@ -90,7 +88,7 @@ VOCAB: list[str] = [
     # Subdivision (2)
     "SUB_4", "SUB_8",
     # Style (5)
-    "STYLE_user", "STYLE_jpop", "STYLE_classical", "STYLE_jazz", "STYLE_other",
+    "STYLE_H1K0", "STYLE_jpop", "STYLE_classical", "STYLE_jazz", "STYLE_other",
     # Function (9)
     "FUNC_verse", "FUNC_prechorus", "FUNC_chorus", "FUNC_bridge",
     "FUNC_intro", "FUNC_outro", "FUNC_interlude", "FUNC_other", "FUNC_unspecified",
@@ -239,8 +237,11 @@ def parse_chord_file(path: Path) -> ChordPeriod:
         )
 
     style = header["style"]
-    if style not in _VALID_STYLES:
-        raise ChordFormatError(f"{fname}: invalid style '{style}'")
+    if not re.match(r'^[A-Za-z][A-Za-z0-9_]*$', style):
+        raise ChordFormatError(
+            f"{fname}: invalid style '{style}' — must be a non-empty identifier"
+            " ([A-Za-z][A-Za-z0-9_]*)"
+        )
 
     raw_function = header.get("function", "")
     if raw_function and raw_function not in _VALID_FUNCTIONS:
@@ -355,7 +356,11 @@ def tokenize_period(period: ChordPeriod) -> list[int]:
     ids.append(TOKEN_TO_ID[f"MODE_{mode}"])
     ids.append(TOKEN_TO_ID[f"TIME_{p.time}"])
     ids.append(TOKEN_TO_ID[f"SUB_{p.subdivision}"])
-    ids.append(TOKEN_TO_ID[f"STYLE_{p.style}"])
+    style_token = f"STYLE_{p.style}"
+    if style_token not in TOKEN_TO_ID:
+        log.warning("unknown style %r — mapping to STYLE_other", p.style)
+        style_token = "STYLE_other"
+    ids.append(TOKEN_TO_ID[style_token])
     ids.append(TOKEN_TO_ID[f"FUNC_{p.function}"])
 
     for bar in p.bars:
diff --git a/tests/fixtures/invalid_bar_count.chord b/tests/fixtures/invalid_bar_count.chord
index 036a16b..149c3a3 100644
--- a/tests/fixtures/invalid_bar_count.chord
+++ b/tests/fixtures/invalid_bar_count.chord
@@ -2,6 +2,6 @@
 # key: C_major
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: other
 
 | C . . . . | G . . . |
diff --git a/tests/fixtures/invalid_chord_symbol.chord b/tests/fixtures/invalid_chord_symbol.chord
index 3cabc8c..b454602 100644
--- a/tests/fixtures/invalid_chord_symbol.chord
+++ b/tests/fixtures/invalid_chord_symbol.chord
@@ -2,6 +2,6 @@
 # key: C_major
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: other
 
 | C . . . | Xyz . . . |
diff --git a/tests/fixtures/midi_export_test.chord b/tests/fixtures/midi_export_test.chord
index 3a36244..d5839ee 100644
--- a/tests/fixtures/midi_export_test.chord
+++ b/tests/fixtures/midi_export_test.chord
@@ -2,6 +2,6 @@
 # key: C_major
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: other
 
 | C . . . | Am7 . . . | F . . . | G7 . . . |
diff --git a/tests/fixtures/valid_b_minor.chord b/tests/fixtures/valid_b_minor.chord
index d13920d..aee8b00 100644
--- a/tests/fixtures/valid_b_minor.chord
+++ b/tests/fixtures/valid_b_minor.chord
@@ -2,6 +2,6 @@
 # key: B_minor
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: other
 
 | Bm . . . | C#m7b5 . . . | D . . . | F#7 . . . |
diff --git a/tests/fixtures/valid_c_major.chord b/tests/fixtures/valid_c_major.chord
index cc5b1ac..acc1af8 100644
--- a/tests/fixtures/valid_c_major.chord
+++ b/tests/fixtures/valid_c_major.chord
@@ -2,7 +2,7 @@
 # key: C_major
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: other
 # function: chorus
 
 | C . . . | Am7 . . . | F/A . . . | G7 . . . | // first half
diff --git a/tests/fixtures/valid_fsharp_major.chord b/tests/fixtures/valid_fsharp_major.chord
index 1de4772..c26b735 100644
--- a/tests/fixtures/valid_fsharp_major.chord
+++ b/tests/fixtures/valid_fsharp_major.chord
@@ -2,6 +2,6 @@
 # key: F#_major
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: other
 
 | F#maj7 . . . | D#m7 . . . | Bmaj7 . F#/A# . | C# . . . |
diff --git a/tests/fixtures/valid_gsharp_minor.chord b/tests/fixtures/valid_gsharp_minor.chord
index 443474d..c688b5e 100644
--- a/tests/fixtures/valid_gsharp_minor.chord
+++ b/tests/fixtures/valid_gsharp_minor.chord
@@ -2,6 +2,6 @@
 # key: G#_minor
 # time: 4/4
 # subdivision: 4
-# style: user
+# style: other
 
 | G#m . . . | A#maj7 . . . | Bmaj7/F# . . . | D#7 . . . |
diff --git a/tests/test_chord_file_parser.py b/tests/test_chord_file_parser.py
index a7158d9..c69a6dc 100644
--- a/tests/test_chord_file_parser.py
+++ b/tests/test_chord_file_parser.py
@@ -40,7 +40,7 @@ class TestParseChordFile:
         assert p.key == "C_major"
         assert p.time == "4/4"
         assert p.subdivision == 4
-        assert p.style == "user"
+        assert p.style == "other"
         assert p.function == "chorus"
 
     def test_c_major_bar_count(self):
diff --git a/tests/test_dataset.py b/tests/test_dataset.py
index e6da403..1e3dcf8 100644
--- a/tests/test_dataset.py
+++ b/tests/test_dataset.py
@@ -21,7 +21,7 @@ def _write_pt(tmp_path: Path, stem: str, n_tokens: int) -> Path:
     """Write a dummy .pt file with sequential token IDs."""
     tokens = torch.arange(n_tokens, dtype=torch.long)
     path = tmp_path / f"{stem}.pt"
-    torch.save({"tokens": tokens, "meta": {"style": "user", "function": "verse"}}, path)
+    torch.save({"tokens": tokens, "meta": {"style": "other", "function": "verse"}}, path)
     return path
 
 
diff --git a/tests/test_tokenizer.py b/tests/test_tokenizer.py
index 3f2656f..1b67a0b 100644
--- a/tests/test_tokenizer.py
+++ b/tests/test_tokenizer.py
@@ -109,7 +109,7 @@ class TestTokenizeStructure:
         assert toks[1] == "MODE_major"
         assert toks[2] == "TIME_4/4"
         assert toks[3] == "SUB_4"
-        assert toks[4] == "STYLE_user"
+        assert toks[4] == "STYLE_other"  # 'unspecified' is not in VOCAB → falls back to STYLE_other
         assert toks[5] == "FUNC_chorus"
 
     def test_bar_token_count_matches_bar_count(self):