Туманомір — вимірювання туману, перш ніж AI-агенти перетворять його на архітектуру

Посилання:

• GitHub
• Розгорнута стаття

Туманомір — CLI на Go, що оцифровує “туман” специфікацій, перш ніж ви дасте AI-агентам перетворити цей туман на архітектуру. Це референсна реалізація методології Джерело Невідомості: специфікації, які споживають AI-агенти, — не істина в останній інстанції, а розподіл можливих реалізацій, тож інструмент вимірює розкид, а не ігнорує його.

Проблема

Передати специфікацію AI-агенту й отримати п’ять по-різному тонко відмінних реалізацій — знайома ситуація, але “тонко відмінних” не має числа. Туманомір дає це число: наскільки трасовані вимоги, наскільки щільні машинозчитувані обмеження, і наскільки далеко одна від одної опиняються незалежні генерації з однієї й тієї ж специфікації.

Метрики

Детермінований шар не потребує LLM і працює як git hook, миттєво. Стохастичний шар генерує N Go-артефактів зі специфікації через фіксований прилад (Ollama) і вимірює, наскільки далеко вони опиняються одна від одної — що ширший розкид, то туманніша специфікація.

CLI

tumanomir check docs/                 # детерміновано, миттєво, без мережі
tumanomir measure spec.md --instrument ollama:qwen3-coder:30b -n 10 \
  --temp 1.0 --sim-threshold 0.95 --num-ctx 8192 --num-predict 2048
tumanomir gate spec.md --instrument ollama:qwen3-coder:30b -n 3 \
  --num-ctx 8192 --num-predict 2048   # обидва шари, для CI
tumanomir calibrate corpus.jsonl      # кореляція Spearman проти розміченого корпусу
tumanomir label <hash-or-prefix> <score>  # єдиний писар результату корпусу

check виконується детерміновано й миттєво. measure/gate вимагають явного --instrument (backend:model) та --num-ctx/--num-predict — gate відмовляється тихо відкочуватися до лише-детермінованого шару, якщо передано температуру, а прилад не резолвиться: тиха деградація була б помилкою цілісності вимірювання, а не зручністю. --format json у check/measure/gate дає один компактний JSON-об’єкт для CI-парсингу.

Приклад детермінованого прогону, коли Туманомір догфудить власну специфікацію:

$ tumanomir check docs/requirements.md
  K_drift:  0.00  [ok]     (threshold 0.20, 0/33 requirements untraced)
  D_const:  0.03  [warn]   (threshold 0.35, 101 markers / 3905 prose tokens)
  D_pair:   —     (stochastic layer: run `tumanomir measure` with an instrument)

Усі стохастичні вимірювання прив’язані до приладу: результати подаються разом з повною конфігурацією приладу й непорівнянні між моделями без перекалібрування.

Архітектура, що заслуговує довіри, а не просто правильна

Детерміновані пакети (internal/metrics, internal/spec, internal/config, internal/calibrate) не мають права торкатися мережі — не як конвенція, а як тест (TestNoNetworkImports), що провалює CI, якщо десь з’явиться імпорт net/*. Саме це робить check і calibrate безпечними як git hook чи в air-gapped CI.

D_const архітектурно не може блокувати гейт (REQ-CHK-06) — зафіксовано в коді як тестований інваріант, а не залишено застереженням у документації, яке можна забути під тиском дедлайну: це лексичний проксі, а не істина щодо точності специфікації.

Сканер $K_{drift}$ переписаний з regexp на hand-written byte scanner (PR #68), знизивши алокації з масштабування за кількістю вимог до фіксованих 14 allocs/op — повний check на специфікації 1МБ виконується за 16.7мс, у межах бюджету 100мс.

Технологічний стек

• Go 1.26 — один бінарник, одна зовнішня залежність (gopkg.in/yaml.v3)
• Ollama — плагований бекенд-прилад для стохастичного шару
• Cobra-подібний CLI, опційний .tumanomir.yaml для налаштувань за замовчуванням

Статус

v0.1: check, measure, gate, calibrate та label — усі реалізовані й працюють наскрізно — 66 комітів, 64 злитих PR, жодного відкату за 25 днів розробки. Тегів ще немає; версія відверто позначена -dev, без претензії на реліз.

Що досі відкрито, за власним звітом проєкту: реального розміченого корпусу для calibrate ще немає, тож порогові значення за замовчуванням (0.20 / 0.35 / 0.30) лишаються гіпотезами, не каліброваними числами. D_pair прив’язаний до приладу — та сама специфікація, той самий прилад, і три послідовні прогони дали вердикти від “ok” до “block”. Перевірений лише один прилад (Ollama, qwen3-coder:30b); бекенди OpenAI/Anthropic не збудовані. Реалізована лише одна проєкція (визначення типів Go), тож v0.1 обмежений Go-проєктами. Повна розгорнута стаття проходить через докази, бенчмарки й чесну “драбину тверджень”, що розділяє доведене від ще гіпотези.

Відкритий код, ліцензія Apache 2.0.

🔗 https://github.com/valpere/tumanomir