====== pi-autoresearch ======

//Vytvořeno: **25.4.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/davebcn87/pi-autoresearch|pi-autoresearch]] je rozšíření a sada skills pro [[ai:platformy:agenti-a-orchestrace:pi-coding-agent|Pi Coding Agent]]. Přidává do Pi autonomní experimentální smyčku: agent navrhne změnu, spustí benchmark, změří metriku, ponechá zlepšení, zahodí regresi a pokračuje další iterací.

===== Rychlé shrnutí =====

  * Projekt není samostatný coding agent, ale **pi package** pro [[https://pi.dev/|Pi]].
  * Hlavní přínos je automatizace měřitelných optimalizačních experimentů.
  * Hodí se pro test speed, build speed, velikost bundlu, LLM training, Lighthouse score nebo jakýkoli jiný cíl s jasnou metrikou.
  * Je inspirovaný projektem [[https://github.com/karpathy/autoresearch|karpathy/autoresearch]], ale je obecnější: není omezený na ML trénování.
  * Podle ''package.json'' jde o balíček ''pi-autoresearch'' verze 1.1.0 s licencí MIT.

===== K čemu je dobrý =====

pi-autoresearch je vhodný tam, kde existuje opakovatelný příkaz a objektivní metrika. Agent pak může dlouho běžet sám a zkoušet varianty, které by člověk ručně testoval pomalu nebo vůbec.

Typické cíle:

  * zrychlení testů,
  * zrychlení buildu,
  * zmenšení výsledného bundlu,
  * optimalizace krátkých ML experimentů,
  * ladění Lighthouse skóre,
  * hledání výkonových zlepšení v konkrétním skriptu nebo knihovně.

Základní pattern je:

<code>
1. definuj cíl a metriku
2. změř baseline
3. uprav kód nebo konfiguraci
4. spusť benchmark
5. výsledek zapiš do logu
6. zlepšení ponech, regresi revertuj
7. opakuj
</code>

===== Přidaná hodnota =====

==== 1. Hotová experimentální infrastruktura pro Pi ====

Pi je záměrně minimalistický agentický harness. pi-autoresearch do něj doplňuje konkrétní workflow pro autonomní optimalizační smyčky.

Balíček obsahuje dvě části:

  * **extension** — nástroje, live widget a dashboard,
  * **skills** — instrukce pro založení, běh, finalizaci a rozšíření experimentální session.

Tím se odděluje obecná infrastruktura od doménového know-how. Extension řeší běh experimentů, logování a UI. Skill určuje, co se optimalizuje, jaký příkaz se spouští a jak se výsledek vyhodnocuje.

==== 2. Agentická smyčka s keep/revert logikou ====

Hlavní smyčka podle README běží autonomně:

<code>
edit → commit → run_experiment → log_experiment → keep/revert → repeat
</code>

Zlepšení se ponechá a typicky se commitne. Horší výsledek, crash nebo selhané kontrolní testy se zahodí a změny se revertují. To je praktické hlavně pro optimalizace, kde vzniká hodně slepých uliček.

==== 3. Persistentní kontext přes soubory ====

Projekt používá soubory v repozitáři, takže session přežije restart nebo vyčerpání kontextového okna.

Důležité soubory:

  * ''autoresearch.md'' — živý dokument se zadáním, metrikami, scope, omezeními a tím, co už bylo zkuseno.
  * ''autoresearch.sh'' — benchmark skript; má vypisovat řádky ve formátu ''METRIC name=value''.
  * ''autoresearch.jsonl'' — append-only log všech běhů, metrik, statusů, commitů a poznámek.
  * ''autoresearch.checks.sh'' — volitelné correctness checks po úspěšném benchmarku.
  * ''autoresearch.hooks/'' — volitelné hooky před a po iteraci.

Díky tomu může nový agent bez původní konverzační historie přečíst ''autoresearch.md'' a ''autoresearch.jsonl'' a pokračovat.

==== 4. Dashboard a confidence score ====

Extension přidává stavový widget, rozšířený dashboard a fullscreen overlay. Widget ukazuje počet běhů, počet ponechaných změn, nejlepší metriku a confidence score.

Confidence score se počítá po třech a více bězích. Používá Median Absolute Deviation jako robustní odhad šumu a porovnává nejlepší zlepšení proti noise flooru.

Výklad podle README:

  * **≥ 2.0×** — zlepšení je pravděpodobně reálné,
  * **1.0–2.0×** — zlepšení je nad šumem, ale marginální,
  * **< 1.0×** — výsledek je pravděpodobně v rámci šumu a stojí za opakované ověření.

Důležité je, že score je jen poradní. Nástroj podle dokumentace sám nic automaticky nezahazuje jen kvůli nízké confidence.

==== 5. Finalizace do reviewovatelných větví ====

Skill ''autoresearch-finalize'' řeší praktický problém: dlouhá experimentální větev bývá špinavá, plná pokusů a revertů. Finalizační skill přečte ''autoresearch.jsonl'', najde ponechané experimenty, navrhne logické skupiny a po schválení vytvoří samostatné větve od merge-base.

Cíl je, aby každá větev obsahovala jednu reviewovatelnou změnu. Skupiny nesmí sdílet soubory, protože mají být aplikovatelné nezávisle.

===== Instalace =====

Rychlá instalace přes Pi package manager:

<code bash>
pi install https://github.com/davebcn87/pi-autoresearch
</code>

Ruční instalace podle README kopíruje extension a skill do uživatelské konfigurace Pi:

<code bash>
cp -r extensions/pi-autoresearch ~/.pi/agent/extensions/
cp -r skills/autoresearch-create ~/.pi/agent/skills/
</code>

Po ruční instalaci je potřeba v Pi použít ''/reload''.

===== Použití =====

==== Založení experimentální session ====

Základní start probíhá přes skill:

<code>
/skill:autoresearch-create
</code>

Skill se zeptá nebo si odvodí:

  * cíl optimalizace,
  * příkaz, který se má spouštět,
  * primární metriku a směr optimalizace,
  * soubory v rozsahu,
  * omezení a pravidla.

Potom vytvoří větev, zapíše ''autoresearch.md'' a ''autoresearch.sh'', změří baseline a začne iterovat.

==== Přímý autoresearch režim ====

Extension přidává i příkaz ''/autoresearch'':

<code>
/autoresearch optimize unit test runtime, monitor correctness
/autoresearch model training, run 5 minutes of train.py and note the loss ratio as optimization target
/autoresearch export
/autoresearch off
/autoresearch clear
</code>

Význam:

  * ''/autoresearch <text>'' — zapne autoresearch režim; pokud existuje ''autoresearch.md'', naváže na existující session.
  * ''/autoresearch off'' — vypne auto-resume a runtime stav, ale nechá ''autoresearch.jsonl''.
  * ''/autoresearch clear'' — smaže ''autoresearch.jsonl'' a resetuje stav.
  * ''/autoresearch export'' — otevře live dashboard v prohlížeči.

==== Finalizace výsledků ====

Po doběhu nebo přerušení experimentů se dá použít:

<code>
/skill:autoresearch-finalize
</code>

Skill připraví změny do samostatných větví pro review. Podle instrukcí ve skillu nejprve navrhne grouping a čeká na schválení.

===== Konfigurace =====

Volitelný soubor ''autoresearch.config.json'' umožňuje nastavit například pracovní adresář a maximální počet iterací:

<code json>
{
  "workingDir": "/path/to/project",
  "maxIterations": 50
}
</code>

''maxIterations'' je důležité bezpečnostní a nákladové omezení. Autonomní smyčka může jinak běžet dlouho a spotřebovávat tokeny i výpočetní prostředky.

===== Backpressure checks =====

Pokud existuje ''autoresearch.checks.sh'', spustí se po každém benchmarku, který skončí úspěšně. Typicky sem patří testy, typecheck nebo lint.

Příklad:

<code bash>
#!/bin/bash
set -euo pipefail
pnpm test --run
pnpm typecheck
</code>

Čas těchto kontrol se nezapočítává do primární metriky. Pokud kontroly selžou, experiment se zaloguje jako ''checks_failed'' a změnu nelze ponechat.

===== Hooks =====

Verze 1.1.0 přidala lifecycle hooks:

  * ''autoresearch.hooks/before.sh'' — běží před každou iterací,
  * ''autoresearch.hooks/after.sh'' — běží po každém ''log_experiment''.

Hooky dostávají na stdin JSON s kontextem a stdout se doručí agentovi jako steer message. To umožňuje doplňkové automatizace, například:

  * načtení externí rešerše před dalším pokusem,
  * zápis poznatků do persistentního journalu,
  * nativní notifikace,
  * anti-thrash pravidla,
  * rotaci nápadů nebo hypotéz.

README zdůrazňuje, že core autoresearch loop nemá o hookách přímé povědomí. Hooky běží vedle něj a jejich výstup se agentovi předá jako další signál.

===== Kdy dává smysl =====

pi-autoresearch dává smysl, když jsou splněné tři podmínky:

  * existuje opakovatelný benchmark nebo měření,
  * výsledek jde převést na jednu hlavní metriku,
  * změny lze bezpečně ponechat nebo revertovat.

Dobré scénáře:

  * výkonové optimalizace s jasným benchmarkem,
  * refaktoring, kde se hlídá rychlost a testy,
  * build/test pipeline s měřitelným časem,
  * experimenty s ML trénováním v krátkých bězích,
  * web performance měřená Lighthousem.

Slabší scénáře:

  * úlohy bez objektivní metriky,
  * velmi pomalé feedback loopy,
  * změny s velkým rizikem poškození dat,
  * oblasti, kde nestačí automatické testy a je nutný lidský úsudek.

===== Limity a rizika =====

  * **Náklady:** autonomní loop může spotřebovat hodně tokenů a výpočetního času. README doporučuje limity na API klíči a ''maxIterations''.
  * **Šum v metrice:** u rychlých nebo kolísavých benchmarků je potřeba měřit vícekrát a používat medián.
  * **Riziko lokálních změn:** nástroj pracuje s git větvemi, commity a reverty; před použitím je potřeba čistý pracovní strom a dobré zálohování.
  * **Bezpečnost:** jde o Pi package s extension kódem, tedy o kód běžící s přístupem k lokálnímu systému.
  * **Neřeší doménu za uživatele:** kvalita výsledků závisí na dobře napsaném ''autoresearch.md'', dobrém benchmarku a správně zvolené metrice.

===== Vztah k původnímu autoresearch =====

Původní [[ai:platformy:agenti-a-orchestrace:autoresearch|autoresearch]] od Andreje Karpathyho je konkrétní ML experiment loop nad trénovacím skriptem a metrikou ''val_bpb''. pi-autoresearch převádí stejný princip do Pi ekosystému a dělá z něj obecný nástroj pro libovolné optimalizační cíle.

Stručně:

  * **karpathy/autoresearch** — konkrétní experimentální repo pro ML trénování.
  * **pi-autoresearch** — Pi extension + skills pro obecné autonomní experimenty.

===== Závěr =====

pi-autoresearch je praktické rozšíření pro případy, kdy má agent optimalizovat něco měřitelného bez průběžného dohledu. Největší hodnota není v jedné konkrétní optimalizační technice, ale v infrastruktuře: benchmark skript, persistentní log, keep/revert workflow, dashboard, confidence score, backpressure checks a finalizace do čistých větví. Nejlépe funguje tam, kde je metrika rychlá, objektivní a dostatečně stabilní.

===== Zdroje =====

  * [[https://github.com/davebcn87/pi-autoresearch|pi-autoresearch – GitHub]]
  * [[https://raw.githubusercontent.com/davebcn87/pi-autoresearch/main/README.md|pi-autoresearch – README]]
  * [[https://raw.githubusercontent.com/davebcn87/pi-autoresearch/main/package.json|pi-autoresearch – package.json]]
  * [[https://raw.githubusercontent.com/davebcn87/pi-autoresearch/main/CHANGELOG.md|pi-autoresearch – changelog]]
  * [[https://raw.githubusercontent.com/davebcn87/pi-autoresearch/main/skills/autoresearch-create/SKILL.md|Skill autoresearch-create]]
  * [[https://raw.githubusercontent.com/davebcn87/pi-autoresearch/main/skills/autoresearch-finalize/SKILL.md|Skill autoresearch-finalize]]
  * [[https://pi.dev/|Pi – homepage]]
  * [[https://github.com/karpathy/autoresearch|karpathy/autoresearch]]