pi-autoresearch

Vytvořeno: 25.4.2026 | Aktualizováno: 25.04.2026 12:36

pi-autoresearch je rozšíření a sada skills pro 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í.

• Projekt není samostatný coding agent, ale pi package pro 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 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.

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:

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

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.

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

edit → commit → run_experiment → log_experiment → keep/revert → repeat

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.

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.

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.

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.

Rychlá instalace přes Pi package manager:

pi install https://github.com/davebcn87/pi-autoresearch

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

cp -r extensions/pi-autoresearch ~/.pi/agent/extensions/
cp -r skills/autoresearch-create ~/.pi/agent/skills/

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

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

/skill:autoresearch-create

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.

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

/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

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.

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

/skill:autoresearch-finalize

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

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

{
  "workingDir": "/path/to/project",
  "maxIterations": 50
}

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.

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:

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

Č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.

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.

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.

• 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.

Původní 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.

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í.

• pi-autoresearch – GitHub
• pi-autoresearch – README
• pi-autoresearch – package.json
• pi-autoresearch – changelog
• Skill autoresearch-create
• Skill autoresearch-finalize
• Pi – homepage
• karpathy/autoresearch