feat: initialize Hypothesis Machine Pi extension
This commit is contained in:
Emil
@@ -0,0 +1,156 @@
|
||||
# Hypothesis Machine
|
||||
|
||||
Hypothesis Machine is an official Pi Coding Agent extension that turns the normal
|
||||
interactive Pi session into the supervisor of a recursive research team. It does
|
||||
not fork Pi or provide another UI. Any child is a persistent Pi `AgentSession` and
|
||||
can dynamically create its own specialized children.
|
||||
|
||||
The working MVP includes recursive/parallel agents, persistent tree recovery,
|
||||
research memory with FTS, local web adapters, a bounded research loop, and a
|
||||
Docker-only experiment runner.
|
||||
|
||||
> **Project status:** early MVP (`0.1.x`). The core is tested locally, including a
|
||||
> real three-level Pi agent run, but public APIs and stored formats may still
|
||||
> change before `1.0`.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Node.js 22.19 or newer and npm;
|
||||
- Pi 0.78 or newer (0.83 recommended) and the normal Pi model/auth configuration;
|
||||
- Docker + Compose for web infrastructure and computational experiments;
|
||||
- roughly 12 GB RAM for the full Firecrawl stack (SearXNG alone is much smaller).
|
||||
|
||||
Runtime dependencies are limited to the four official Pi packages, `typebox`
|
||||
(Pi's tool schemas), and `yaml` (agent/config frontmatter). SQLite comes from
|
||||
Node.js; no external database library is used.
|
||||
|
||||
## Install and connect to Pi
|
||||
|
||||
From this directory:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run typecheck && npm test && npm run build
|
||||
pi install .
|
||||
```
|
||||
|
||||
For development without installation:
|
||||
|
||||
```bash
|
||||
pi --extension ./src/index.ts
|
||||
```
|
||||
|
||||
Pi remains the same chat interface, model selector, credential store, session UI,
|
||||
and streaming runtime. Do not install third-party subagent extensions for this
|
||||
package; Hypothesis Machine has its own recursive implementation.
|
||||
|
||||
Pi 0.78 passes its official `ModelRegistry` directly to children. Pi 0.83+
|
||||
uses the newer shared `ModelRuntime`. Neither path reads or copies keys in the
|
||||
extension. After updating this local package, restart Pi or run `/reload`.
|
||||
|
||||
Optional project configuration:
|
||||
|
||||
```bash
|
||||
mkdir -p .hypothesis-machine
|
||||
cp .hypothesis-machine.example.yaml .hypothesis-machine/config.yaml
|
||||
```
|
||||
|
||||
## Local web infrastructure
|
||||
|
||||
```bash
|
||||
docker compose -f infra/compose.yaml pull
|
||||
docker compose -f infra/compose.yaml up -d
|
||||
curl 'http://127.0.0.1:8888/search?q=pi&format=json'
|
||||
curl -s http://127.0.0.1:3002/ | head
|
||||
```
|
||||
|
||||
Search routes to SearXNG; reading/crawling routes to self-hosted Firecrawl. The
|
||||
Browser Use fallback is an optional local adapter because current Browser Use
|
||||
requires a separate model credential; see
|
||||
[`services/browser-worker/README.md`](services/browser-worker/README.md).
|
||||
|
||||
## First run
|
||||
|
||||
Start normal Pi in the project, then enter:
|
||||
|
||||
```text
|
||||
Исследуй возможность применения метода A к задаче B.
|
||||
Создай независимые направления для литературы, данных и критики.
|
||||
Разреши агентам создавать подагентов.
|
||||
Продолжай до появления проверяемой гипотезы или до трёх
|
||||
итераций без информационного прироста.
|
||||
```
|
||||
|
||||
Or use `/research <goal>`. The Supervisor calls coded tools; `spawn_agent` creates
|
||||
a generated Markdown spec and a separate Pi session. A child can call the same
|
||||
tool to create a grandchild. Foreground spawns return the result immediately;
|
||||
background branches are controlled with `agent_control`.
|
||||
|
||||
## Commands
|
||||
|
||||
- `/team` — tree, tasks, and statuses;
|
||||
- `/research <goal>` — start the explicit bounded loop;
|
||||
- `/research-status`, `/research-pause`, `/research-resume`, `/research-stop`;
|
||||
- `/findings`, `/hypotheses`.
|
||||
|
||||
The same operations are model-callable tools, so natural language such as “create
|
||||
an independent critic”, “steer agent X”, or “cancel that branch” works without a
|
||||
separate command UI.
|
||||
|
||||
## State and memory
|
||||
|
||||
```text
|
||||
.hypothesis-machine/
|
||||
├── runs/<run>/manifest.json, agents/*.md, sessions/*.jsonl
|
||||
├── memory/{findings,hypotheses,questions,syntheses,decisions,agent-lessons}/
|
||||
├── sources/<source-id>/{original.bin,metadata.json}
|
||||
├── artifacts/web-cache/
|
||||
├── experiments/<exp-id>/
|
||||
└── index.sqlite
|
||||
```
|
||||
|
||||
Pi JSONL stores conversations/tool calls/usage. Hypothesis Machine stores only
|
||||
domain results and relationships. Markdown and original bytes are source of
|
||||
truth; SQLite is a rebuildable search index. A model answer without sources cannot
|
||||
be published as `corroborated`.
|
||||
|
||||
## Experiments
|
||||
|
||||
`run_experiment` requires hypothesis, data, baseline, split, metrics, success and
|
||||
refutation criteria, confounders, and resource limits before execution. The plan
|
||||
hash is frozen, source is written to an isolated experiment directory, and Docker
|
||||
runs with no network or secrets. Results include logs, environment, metrics/files
|
||||
created by the experiment, and space for independent `review.md`. A different
|
||||
agent must call `review_experiment`; code rejects self-review and records one of
|
||||
the final hypothesis verdicts in the experiment manifest.
|
||||
|
||||
## Security and limitations
|
||||
|
||||
Read [`docs/security.md`](docs/security.md) before autonomous work. Web content is
|
||||
untrusted, private networks are blocked, and Docker never degrades to host
|
||||
execution. Current MVP limitations:
|
||||
|
||||
- live recursive model execution requires configured Pi credentials and was not
|
||||
exercised by the free automated suite;
|
||||
- Browser Use is an adapter contract, not enabled in default Compose;
|
||||
- Firecrawl consumes substantial resources and its upstream images are not digest-pinned;
|
||||
- independent review is a dynamic agent pattern, not a hard-coded mandatory role;
|
||||
- the SQLite API in Node 22 is still marked experimental;
|
||||
- strict filesystem isolation for Pi read-only tools requires an OS/Pi sandbox.
|
||||
|
||||
Troubleshooting: `docker compose -f infra/compose.yaml ps`, verify SearXNG JSON is
|
||||
enabled, verify Firecrawl at port 3002, run `docker info`, and use
|
||||
`/research-status`. Active children from an unclean shutdown restore as
|
||||
`interrupted`; their session file and lineage remain available.
|
||||
|
||||
Design details: [`docs/architecture.md`](docs/architecture.md), verified Pi APIs:
|
||||
[`docs/pi-capabilities.md`](docs/pi-capabilities.md), development:
|
||||
[`docs/development.md`](docs/development.md).
|
||||
|
||||
## Contributing and releases
|
||||
|
||||
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the local workflow and
|
||||
[`docs/releasing.md`](docs/releasing.md) for the maintainer checklist. Please
|
||||
report security issues privately as described in [`SECURITY.md`](SECURITY.md).
|
||||
|
||||
Released under the [MIT License](LICENSE).
|
||||
Reference in New Issue
Block a user