Skip to content
BrainlessLab BrainlessLab BrainlessLab

Maintain an experiment workspace

A workspace preserves the question, plans, execution attempts, analyses and current interpretation of related work. This example checks the reporting workflow with four nodes and six ticks per trial. Its small development sample supports no scientific comparison claim.

Create and run the workspace

Run these commands from the repository root:

Terminal window
uv sync --locked --group dev --extra reports
uv run brainlesslab workspace init research/workspaces/report-demo --id report-demo --title "Report workflow demonstration"
cp python/plans/report-sweep.toml research/workspaces/report-demo/plans/
cp python/plans/report-followup.toml research/workspaces/report-demo/plans/
uv run brainlesslab workspace check research/workspaces/report-demo --json
uv run brainlesslab check research/workspaces/report-demo/plans/report-sweep.toml
lab_sweep_receipt="$(uv run brainlesslab run research/workspaces/report-demo/plans/report-sweep.toml --root research/workspaces/report-demo/records --backend cpu --batch-size 2)"
lab_sweep_record="$(uv run python -c 'import json, sys; print(json.loads(sys.argv[1])["record"])' "$lab_sweep_receipt")"
uv run brainlesslab inspect "$lab_sweep_record"
uv run brainlesslab workspace attach research/workspaces/report-demo --record "$lab_sweep_record"

Expect valid preflight, complete execution and valid checksums. The run prints a JSON receipt containing its path and lifecycle status. The two gain conditions share declared world, construction and mechanism streams. Each condition has two independent blocks with two trials each. Ticks and nodes add no independent samples.

If an attempt fails, preserve the printed record path and inspect its failure. Finalised failed or incomplete attempts can still be attached as audit references. Missing output is not a successful result. Plans and authored notes can be tracked in Git; local records and generated builds are excluded by default. An active or unfinalised attempt stays visible as unattached until finalisation.

The follow-up uses a different root seed and seed partition. It demonstrates a linked investigation rather than sealed confirmation:

Terminal window
lab_followup_receipt="$(uv run brainlesslab run research/workspaces/report-demo/plans/report-followup.toml --root research/workspaces/report-demo/records --backend cpu --batch-size 2)"
lab_followup_record="$(uv run python -c 'import json, sys; print(json.loads(sys.argv[1])["record"])' "$lab_followup_receipt")"
uv run brainlesslab workspace attach research/workspaces/report-demo --record "$lab_followup_record"
uv run python - <<'PY'
from pathlib import Path
import tomllib
import tomli_w


root = Path("research/workspaces/report-demo")
index = root / "workspace.toml"
data = tomllib.loads(index.read_text())
data["references"][1]["followup_of"] = data["references"][0]["id"]
index.write_text(tomli_w.dumps(data))
(root / "README.md").write_text(
    "# Report workflow demonstration\n\n"
    "## Question\n\nCan we preserve and share two small development attempts?\n\n"
    "## Interpretation\n\nThese diagnostic trials check the workflow. "
    "They do not establish a gain effect or a learning mechanism.\n\n"
    "## Next action\n\nInspect the report and its retention declarations.\n"
)
PY
uv run brainlesslab workspace status research/workspaces/report-demo --json
uv run brainlesslab workspace check research/workspaces/report-demo --json

Status gives bounded authored context and recent work. Use workspace check for full record integrity checks. The reference link does not pool the two runs. Update the README’s Question, Interpretation and Next action sections as the investigation develops. Counts cover indexed references. The example attaches records; its plan files remain ordinary authoring until you choose to index them in workspace.toml.

Build an authored report

Initialisation selects the currently attached records and creates editable sources:

Terminal window
uv run brainlesslab report init research/workspaces/report-demo --id report-demo --title "Small sweep and follow-up"
uv run python - <<'PY'
from pathlib import Path
import tomllib
import tomli_w


draft = Path("research/workspaces/report-demo/reports/report-demo")
path = draft / "report.toml"
data = tomllib.loads(path.read_text())
data["description"] = "A diagnostic check of portable research reporting."
data["tags"] = ["workflow", "development"]
data["selection"] = "Both workflow attempts are shown separately; no outcomes are pooled."
data["supplements"] = [data["records"][0]]
data["views"].append({
    "id": "gain-sweep", "kind": "sweep", "records": [data["records"][0]],
    "axis": "input_gain", "caption": "Recorded raw outcomes from the diagnostic sweep.",
    "alt": "Raw delayed-cue outcomes at input gains 0.5 and 1.0.",
})
path.write_text(tomli_w.dumps(data))
(draft / "report.md").write_text(
    "## Question\n\nCan a small paired sweep and follow-up be shared with their provenance?\n\n"
    "## Method\n\nEach condition uses four Falandays nodes, six ticks per trial, "
    "two independent construction blocks and two trials per block. "
    "The sweep conditions share declared world streams. "
    "The follow-up uses a separate development seed partition.\n\n"
    "## Results\n\n{{view:outcomes}}\n\n{{view:gain-sweep}}\n\n"
    "## Interpretation\n\nThese diagnostic records demonstrate the workflow. "
    "They support no scientific comparison or biological claim.\n\n"
    "## Retention and limitations\n\nThe sweep's original record is retained as a supplement. "
    "The follow-up retains replication settings, summaries and unit identities in the core. "
    "Its omitted trial values require a new simulation attempt; "
    "the original trial values cannot be reanalysed from this publication. "
    "No independent rerun or reanalysis is claimed.\n\n"
    "## Next steps\n\nDesign scientific controls and sample size before making a comparison.\n"
)
PY
uv run brainlesslab report check research/workspaces/report-demo/reports/report-demo --json
uv run brainlesslab report build research/workspaces/report-demo/reports/report-demo

Open research/workspaces/report-demo/reports/report-demo/build/index.html in a browser. It contains the article, tables and figure without fetching external assets. Check that captions match their supporting runs and missing adjustments remain explicitly unavailable.

Export a revision

Terminal window
uv run brainlesslab report export research/workspaces/report-demo/reports/report-demo --revision 1 --output research/reports/report-demo/v1

Expect standalone HTML, article.json, core.zip, the selected run-data supplement, authoring sources and release.json. Export validates hashes and enforces a 25 MiB total revision cap. The destination must be new; accepted revisions are immutable.

Share index.html directly, or follow Share results for repository publication. The format reference explains custom analysis receipts and reproduction capabilities.