discussions/.brainstorm/modulair-rag.md

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

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-валидации)