# ModulAIr RAG — brainstorm capture

> Captured 2026-05-05 in single-agent session inside `.meeting-room/`.
> Source scenario: `scenarios/modulair.md` (4-agent meeting frontmatter, не запускалось — пользователь предпочёл одного собеседника).
> Prior multi-agent transcript: `source/2026-05-03-modulair.md` — там пользователь с другим ассистентом прошёл первый круг и накопил пул tooling-кандидатов (Marker, Repomix, ArchiveBox, Memos, Hermes-agent, и др.).
> Mature design: `~/projects/.wiki/concepts/modulair-rag-design.md` — этот файл фиксирует процесс, не финальное решение.

---

## Контекст ModulAIr

ModulAIr — AI-управляемый секвенсор/контроллер для еврорэка на Pico 2 W. Декомпозирован на 6 sub-projects:

- `modulair-hw` — KiCad PCB (Pico 2 W + DAC + Gate-drivers + ADC + MIDI TRS + audio preamp + eurorack-питание)
- `modulair-fw` — прошивка Pico 2 W
- `modulair-script` — Teletype-style DSL + интерпретатор
- `modulair-mcp` — MCP-мост между LLM и Pico
- **`modulair-rag`** — база знаний ◄ предмет этого брейнсторма
- `modulair-agent` — Hermes-агент как top-level orchestrator

**Сквозная архитектурная развилка решена: Variant A — Pico-autonomous, LLM-conductor.** Pico исполняет скрипты sample-accurate, LLM через MCP мутирует паттерны/скрипты, но не сидит в горячем audio-пути. Wi-Fi latency перестаёт быть проблемой.

## RAG-решения и почему

### Стратегия — c-tiered (а не плоский vector RAG)

Чисто вектор-RAG плох на factual-лукапах в синт-домене:
- Эмбеддинги "0–8V" / "±5V" / "0V to 10V" близки в семантическом пространстве, но это разные факты
- Отрицание ("у X нет Reset-входа") не работает — ретривер тащит чанки где есть "Reset" и "X" рядом
- Сравнения требуют JOIN, а не top-k retrieval
- Чанкинг ломает таблицы datasheet'ов

→ **Tier 1** vector (manuals / theory / VCV source / forum threads) — recall-heavy, fuzzy.
→ **Tier 2** structured Postgres (module specs из ModularGrid + vendor parsers) — precision-heavy, точные ответы.
→ **Tier 3** ручные аннотации (~50 модулей личного рэка, calibration quirks, undocumented behavior).

### Storage

- **Postgres (cloud, существующий)** для Tier 2/3. **Не MariaDB:** JSONB для переменной формы jack-списков, pgvector как открытая дверь, recursive CTE + lateral joins зрелее, array-типы родные, MCP/ORM-экосистема Postgres-first.
- **LightRAG #2 (новый instance с `working_dir=modulair-rag`)** для Tier 1. Текущий LightRAG-корпус не трогаем — он для других задач.
- **Не pgvector unified** — это потребовало бы миграцию текущего LightRAG.
- **Не Neo4j** — overkill для тысяч модулей; relations моделируются плоскими таблицами.

### Scope первой итерации — (II) MVP на full-scrape ModularGrid

~15k модулей, ~1 месяц. Альтернативы: (I) Top-50 за 2 недели — учиться на знакомом; (III) всё сразу за 1.5–2 мес. Выбрано (II) — компромисс между амбицией и сроками.

Что меняется при этом скоупе:
- **Per-field provenance обязательна** — без неё не отличить достоверный ±5V от LLM-угадки
- **LLM-extraction как этап pipeline** — jacks/polarity/range живут в свободном тексте описаний и manual PDF, нужен LLM-проход по 15k
- **Validation gates first-class** — voltage standards становятся правилами (audio типично ±5V, anomaly → флаг)

### Pipeline — immutable layered (L1-L4)

```
L1  raw HTML        → MinIO bucket, content-addressed (sha256)
L2  DOM extracts    → JSONL/run, структурные поля (HP, manufacturer, current_ma)
L3  LLM extracts    → JSONL/run, jacks/polarity/range из свободного текста
L4  Postgres        → "current state", собран из L2+L3+Tier-3
```

Зачем слоями: на MVP схема меняется ~5×, LLM-промпт ~10×. Без immutable слоёв каждое изменение = повторный scrape (медленно, rate-limit) + LLM-проход (дорого). С immutable — пере-extract из L2/L3 за минуты.

### Source стратегия — multi-source

```
1. Vendor-side parsers (top-10):
   pichenettes/eurorack (canonical Mutable), Make Noise, Intellijel,
   Doepfer, ALM, Noise Engineering, Befaco, 4ms, Erica, Tiptop
2. ModularGrid scrape (HTML, ≤1 RPS, weekly cron)
   robots.txt allow модули и .json; их официальный API паузнут из-за EU copyright reform
3. Tier 3 — ручные аннотации (~50 модулей личного рэка)
```

Не зависимы от ModularGrid одного — фрагильно (DOM может смениться, anti-scrape, юр. неопределённость).

### Extractor LLM — Ollama Cloud sample first, не Haiku

Решение: первый прогон через Ollama Cloud (GLM-5.1 / qwen) на golden set, валидация против Haiku 4.5 как benchmark. Если разница <5pp на ключевых метриках — Ollama, бесплатно. Если ≥10pp — Haiku-tiered с Sonnet 4.6 на flagged записях.

**Golden set protocol** (1–2 дня ручной работы):
- ~40 модулей: 20 Mutable (pichenettes/eurorack), 10 Doepfer, 5 Make Noise/Intellijel, 5 edge-case
- JSON-эталон per модуль: `{name, direction, signal_type, polarity, range_v_min, range_v_max}`
- Метрики/пороги: F1 signal_type ≥0.85, Acc polarity ≥0.85, MAE range ≤0.5V, hallucination ≤5%, miss ≤15%
- Артефакты в git: `golden/`, `runs/<model>/`, `metrics/`

### Provenance — module_facts + materialized consensus view

```sql
module_facts (
  module_id, field, value JSONB, confidence REAL,
  source_layer  -- 'L2-dom' | 'L3-llm-haiku' | 'L3-llm-sonnet' | 'tier3-manual'
  source_ref,   -- 'scrape-2026-05-05/mutable-rings.json#desc-jacks'
  scraped_at
)
```

Плоские `modules` / `jacks` — materialized view "consensus" поверх highest-confidence values. MCP читает плоский view, валидатор/админка — `module_facts` напрямую. Альтернатива (`<col>_confidence`/`<col>_source` рядом) отвергнута — на 30+ полях шум.

### Tier 1 corpus — phased

**Phase 1 (MVP):** ModularGrid descriptions всех 15k (из L1) + top-100 vendor manuals + VCV Rack Fundamental/Library source + 30–50 hand-curated theory статей.
**Phase 2 post-MVP:** vendor manuals top-500, YouTube whisper-транскрипты топ-creator'ов, selected forum threads.
**Phase 3:** long-tail manuals, full forum scrape с quality filter.

### Deploy shape — Docker compose, своё железо

Existing: Postgres, Traefik, Portainer, kicad-mcp (для других sub-projects).

5 новых контейнеров для modulair-rag:
1. `lightrag-modulair` — Tier 1 vector, working_dir отдельный
2. `minio` — L1 raw HTML cache, content-addressed
3. `modulair-pipeline` — scraper + extractor + loader, cron внутри
4. `tier1-converter` — Marker + Repomix + Firecrawl batch jobs
5. `modulair-mcp` — MCP-сервер для Hermes (`module_spec`, `concept_search`, `module_compare`, `module_pairs`, `module_text`, `rack_modules`, `provenance`)

### Orchestration — Hermes, не n8n

Hermes-agent живёт в отдельном sub-project и через MCP зовёт наш `modulair-mcp` + (будущий) `firmware-mcp` + собственные Python-skills для batch (`run_repomix`, `run_marker`). n8n из плана убран — дублирует Hermes.

Phases:
- Phase 1 — cron внутри контейнеров
- Phase 2 — Changedetection.io webhooks → Hermes scheduled-automations
- Phase 3 — расширение Hermes skills (multi-source priorisation, feedback-loop из Memos/Obsidian, vendor-парсеры как skills)

## Что отвергнуто и почему

| Отвергнуто | Причина |
|---|---|
| Pure vector RAG (c-flat) | Factual-лукапы галлюцинируют; embeddings не различают voltage ranges |
| Postgres + pgvector unified (α) | Заставит мигрировать существующий LightRAG-корпус |
| MariaDB | JSONB и pgvector будущего — типпинг-пойнт за Postgres |
| Neo4j | Overkill для тысяч модулей; relations плоско моделируются |
| n8n | Дублирует Hermes-agent |
| markitdown как primary | Marker лучше PDF, Repomix лучше код, Firecrawl лучше JS-сайты |
| tree-sitter primary chunking | Repomix даёт structure-aware MD из коробки |
| DVC | pg_dump + content-addressed MinIO покрывают provenance |
| kicad-mcp в modulair-rag | Out of scope; живёт в modulair-agent / modulair-hw |
| ArchiveBox в MVP | Heavy (Docker+Chrome+Node), своя scraper-реализация дешевле для targeted-scrape |

## Открытые вопросы (не блокируют MVP)

- Финальный размер golden-set (40 принято; ужесточение MAE до 0.2V для CV-модулей — после первого прогона)
- Music theory sources — конкретный список 30–50 статей не зафиксирован (упомянуты Allen Strange, Whitwell, SoS Synth Secrets, Eno strategies)
- Phasing для feedback-loop (Memos / Obsidian #feedback) — Phase 2, конкретная реализация позже
- Где физически живёт kicad-mcp (host stdio vs Docker) — релевантно для modulair-agent / modulair-hw, не для modulair-rag

## Tooling из исходного транскрипта 2026-05-03

Я провалил первый проход — не прочитал транскрипт перед тем как предлагать стэк. Память записана: `feedback_read_source_transcripts.md`. Финальный мерж stack'ов:

| Категория | Что взято | Что отвергнуто |
|---|---|---|
| PDF→MD | **Marker** (primary), **LlamaParse** (fallback) | markitdown как primary, Docling (только если Marker не установится) |
| Web→MD | **Firecrawl** (batch), **Jina Reader** (одноразовый) | Trafilatura |
| Code→MD | **Repomix** | tree-sitter с нуля |
| Web archive | **Wallabag** в Phase 2 | ArchiveBox в MVP, Linkwarden, Shiori |
| Change detection | **Changedetection.io** в Phase 2 | (alone, без n8n) |
| Orchestration | **Hermes-agent** | n8n, Huginn |
| Data versioning | `pg_dump` + content-addressed MinIO | DVC |
| Feedback loop | **Memos** или **Obsidian** в Phase 2 | (одно из двух) |
| Container UI | **Portainer** (existing) | Dockge |
| Vector store | **LightRAG** (existing для других, новый instance для modulair) | ChromaDB, Pinecone, GraphRAG |
| Algo composition | **music21** — для modulair-agent, не RAG | — |
| Embedded DSP | Pure Data + hvcc / Faust — для modulair-fw audio sub-project, не RAG | — |
| EDA → MD | **kicad-mcp** существующий, для modulair-hw / modulair-agent | KiCad-CLI / KiBot — out of scope для modulair-rag |

## Меморики, появившиеся за сессию

- `feedback_meeting_room_workspace.md` — `.meeting-room` это brainstorm-зона, артефакты идут в `.brainstorm/` или global wiki, не через "transit-zone autopilot"
- `project_extend_discipline_for_meeting_room.md` — открытый todo расширить project-discipline под brainstorm-workspaces
- `feedback_read_source_transcripts.md` — `.meeting-room/source/<date>-<topic>.md` это pre-loaded user research, читать до предложения стэка

## Следующие шаги

1. Брейнсторм per остальным 5 sub-projects (`modulair-hw`, `modulair-fw`, `modulair-script`, `modulair-mcp`, `modulair-agent`)
2. Когда RAG-implementation начнётся — поднять структуру репозитория `modulair-rag` где-то в `~/projects/`, скелет compose.yml, `.tasks/STATUS.md` под фактический проект
3. Заведение golden-set (1–2 дня ручной работы — это первое что нужно сделать; в MVP это блокирующая зависимость для extractor-валидации)