From 0f76613aee109e2a5a239e1261c9517b990971a3 Mon Sep 17 00:00:00 2001 From: vitya Date: Tue, 5 May 2026 14:39:05 +0300 Subject: [PATCH] Track existing modulair-rag brainstorm capture Pre-promotion commit so the next 'git mv' to .archive/ shows as a rename. Co-Authored-By: Claude Opus 4.7 (1M context) --- .brainstorm/modulair-rag.md | 178 ++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 .brainstorm/modulair-rag.md diff --git a/.brainstorm/modulair-rag.md b/.brainstorm/modulair-rag.md new file mode 100644 index 0000000..88bb9f7 --- /dev/null +++ b/.brainstorm/modulair-rag.md @@ -0,0 +1,178 @@ +# 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//`, `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` напрямую. Альтернатива (`_confidence`/`_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/-.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-валидации)