research-diff 0.1.0__tar.gz

research_diff-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.png binary

research_diff-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q
+
+  map:
+    # The README's research map is drawn from examples/: it must be current.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      - name: The research map is current (if not, run research-diff readme and commit)
+        run: research-diff readme --check

research_diff-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: release
+
+# A tag vX.Y.Z publishes that version to PyPI through trusted publishing: no token is stored anywhere. PyPI accepts the
+# upload only from this workflow, in this repository, in the `pypi` environment.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: The tag is the version in pyproject.toml
+        run: |
+          v=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          [ "v$v" = "$GITHUB_REF_NAME" ] || { echo "tag $GITHUB_REF_NAME, but pyproject.toml says $v"; exit 1; }
+      - run: python -m pip install build && python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

research_diff-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv*/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+/out/
+docs/diagrams/*.png

research_diff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 simplifiedmachine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

research_diff-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: research-diff
+Version: 0.1.0
+Summary: Maps your research from its notes, experiment configs, results and paper (questions, hypotheses, experiments, results, claims) and shows what each iteration changed. Built for exploring ideas with AI coding agents.
+Project-URL: Homepage, https://github.com/simplifiedmachine/research-diff
+Project-URL: Documentation, https://github.com/simplifiedmachine/research-diff/wiki
+Author: simplifiedmachine
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,experiment-tracking,hypotheses,mcp,reproducibility,research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: system-diff==0.1.0
+Provides-Extra: dev
+Requires-Dist: mcp>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# research-diff
+
+Maps your research from its notes, experiment configs, results and paper (questions, hypotheses, experiments,
+results, claims) and shows what each iteration changed. Built for exploring ideas with AI coding agents.
+
+<!-- research-map:begin -->
+![Research map, generated from the notes, configs, results and paper](https://raw.githubusercontent.com/simplifiedmachine/research-diff/main/docs/research.svg)
+
+<details><summary>1 open warning</summary>
+
+- H2 is open and no experiment tests it
+
+</details>
+<!-- research-map:end -->
+
+The map above is this repository's own example (`examples/batch-size`), regenerated from its files on every change.
+
+## What it reads
+
+Markers in your own files, in one grammar: an id (`Q` question, `H` hypothesis, `E` experiment, `R` result,
+`C` claim, and a number) and a title, then links and a status on the lines after it.
+
+```markdown
+## H2: Learning-rate warm-up removes the gap      <- notes (Markdown): a heading or a list item
+answers: Q1
+status: open                                      <- open | supported | refuted | anything you like
+```
+
+| Where | How |
+|---|---|
+| Notes (`.md`) | definitions as above; `tests:`, `of:`, `supports:`, `weakens:`, `relies on:`, `metrics: acc=0.91` |
+| Experiment configs (YAML, JSON, TOML) | a `research:` block: `id`, `title`, `tests`, `status`, and `results: out/e1.json`, whose numbers become the result `E1.results` |
+| Scripts and notebooks | a comment: `# research-diff: E2 tests H2` |
+| The paper (LaTeX) | a comment: `% C1: Small batches win` and `% relies on: H1, R1`; the paragraph's `\cite{…}` become its sources; `% expects: E1.results acc.batch32 > 0.85` warns when a result stops meeting it |
+
+The map is built from markers only, so the same files always give the same map. It warns when a claim relies on
+nothing or on a refuted hypothesis, when a number no longer meets what a claim `expects:`, when an open hypothesis has no experiment, and when a link points at nothing.
+
+## Use
+
+```sh
+pipx install research-diff
+research-diff map --out docs            # research.svg and research.json
+research-diff diff --base HEAD          # what your uncommitted iteration did
+research-diff sync                      # MLflow / W&B runs into research/runs.json
+research-diff checkpoint                # mark what you have understood
+research-diff diff                      # only what came after that
+```
+
+A diff reads like: *Adds 1 hypothesis (H3); H1: open → refuted; E1.results acc.b32: 0.874 → 0.881 (+0.8%); 1 new
+link; 2 new warnings (C1 relies on H1, which is refuted…).* It comes with the exact list (`plan.txt`) and a picture of
+only what changed (`diff.svg`).
+
+## With AI coding agents
+
+```sh
+pipx inject research-diff mcp
+research-diff setup claude     # a Stop hook, a skill and the MCP server (--scope project, --undo)
+research-diff watch            # http://127.0.0.1:8766/ : the research diff since your checkpoint, live
+```
+
+After every Claude Code turn one line says what changed in the research. The agent's tools: `research_diff`,
+`research_map`, `log_result` (records a run's metrics and what it supports or weakens in `research/log.md`, so it is
+on the map and in git) and `checkpoint`. The pictures, snapshots and live page are
+[system-diff](https://github.com/simplifiedmachine/system-diff)'s.
+
+## Experiment trackers
+
+Runs logged to MLflow (its local `mlruns/` store) or W&B (its local `wandb/` folders) become results of the experiment
+they are tagged with: `research-diff.experiment` (or `research_id`) as an MLflow tag or param, `research_id` in the W&B
+config. Tracker folders are usually git-ignored, so `research-diff sync` copies their runs into `research/runs.json`,
+which is tracked: the runs are then on the map, in git and in the next diff. The hook, the live page and the MCP tools
+sync on their own.
+
+## Markers suggested by your LLM
+
+```sh
+research-diff suggest                 # notes and paper files with no marker yet, or name the files
+git apply .git/research-diff/suggest.patch
+```
+
+Your LLM (the one your Claude Code uses) proposes markers for what the text already says. Each proposal is checked
+before it reaches the patch: a real line of a file it was shown, a marker in that file's own form, and no id that is
+already used. Nothing is written until you apply the patch.
+
+## License
+
+MIT

research_diff-0.1.0/README.md

@@ -0,0 +1,88 @@
+# research-diff
+
+Maps your research from its notes, experiment configs, results and paper (questions, hypotheses, experiments,
+results, claims) and shows what each iteration changed. Built for exploring ideas with AI coding agents.
+
+<!-- research-map:begin -->
+![Research map, generated from the notes, configs, results and paper](https://raw.githubusercontent.com/simplifiedmachine/research-diff/main/docs/research.svg)
+
+<details><summary>1 open warning</summary>
+
+- H2 is open and no experiment tests it
+
+</details>
+<!-- research-map:end -->
+
+The map above is this repository's own example (`examples/batch-size`), regenerated from its files on every change.
+
+## What it reads
+
+Markers in your own files, in one grammar: an id (`Q` question, `H` hypothesis, `E` experiment, `R` result,
+`C` claim, and a number) and a title, then links and a status on the lines after it.
+
+```markdown
+## H2: Learning-rate warm-up removes the gap      <- notes (Markdown): a heading or a list item
+answers: Q1
+status: open                                      <- open | supported | refuted | anything you like
+```
+
+| Where | How |
+|---|---|
+| Notes (`.md`) | definitions as above; `tests:`, `of:`, `supports:`, `weakens:`, `relies on:`, `metrics: acc=0.91` |
+| Experiment configs (YAML, JSON, TOML) | a `research:` block: `id`, `title`, `tests`, `status`, and `results: out/e1.json`, whose numbers become the result `E1.results` |
+| Scripts and notebooks | a comment: `# research-diff: E2 tests H2` |
+| The paper (LaTeX) | a comment: `% C1: Small batches win` and `% relies on: H1, R1`; the paragraph's `\cite{…}` become its sources; `% expects: E1.results acc.batch32 > 0.85` warns when a result stops meeting it |
+
+The map is built from markers only, so the same files always give the same map. It warns when a claim relies on
+nothing or on a refuted hypothesis, when a number no longer meets what a claim `expects:`, when an open hypothesis has no experiment, and when a link points at nothing.
+
+## Use
+
+```sh
+pipx install research-diff
+research-diff map --out docs            # research.svg and research.json
+research-diff diff --base HEAD          # what your uncommitted iteration did
+research-diff sync                      # MLflow / W&B runs into research/runs.json
+research-diff checkpoint                # mark what you have understood
+research-diff diff                      # only what came after that
+```
+
+A diff reads like: *Adds 1 hypothesis (H3); H1: open → refuted; E1.results acc.b32: 0.874 → 0.881 (+0.8%); 1 new
+link; 2 new warnings (C1 relies on H1, which is refuted…).* It comes with the exact list (`plan.txt`) and a picture of
+only what changed (`diff.svg`).
+
+## With AI coding agents
+
+```sh
+pipx inject research-diff mcp
+research-diff setup claude     # a Stop hook, a skill and the MCP server (--scope project, --undo)
+research-diff watch            # http://127.0.0.1:8766/ : the research diff since your checkpoint, live
+```
+
+After every Claude Code turn one line says what changed in the research. The agent's tools: `research_diff`,
+`research_map`, `log_result` (records a run's metrics and what it supports or weakens in `research/log.md`, so it is
+on the map and in git) and `checkpoint`. The pictures, snapshots and live page are
+[system-diff](https://github.com/simplifiedmachine/system-diff)'s.
+
+## Experiment trackers
+
+Runs logged to MLflow (its local `mlruns/` store) or W&B (its local `wandb/` folders) become results of the experiment
+they are tagged with: `research-diff.experiment` (or `research_id`) as an MLflow tag or param, `research_id` in the W&B
+config. Tracker folders are usually git-ignored, so `research-diff sync` copies their runs into `research/runs.json`,
+which is tracked: the runs are then on the map, in git and in the next diff. The hook, the live page and the MCP tools
+sync on their own.
+
+## Markers suggested by your LLM
+
+```sh
+research-diff suggest                 # notes and paper files with no marker yet, or name the files
+git apply .git/research-diff/suggest.patch
+```
+
+Your LLM (the one your Claude Code uses) proposes markers for what the text already says. Each proposal is checked
+before it reaches the patch: a real line of a file it was shown, a marker in that file's own form, and no id that is
+already used. Nothing is written until you apply the patch.
+
+## License
+
+MIT

research_diff-0.1.0/docs/research.svg

@@ -0,0 +1,78 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1284" height="296" viewBox="0 0 1284 296" role="img" aria-label="Research map">
+<style>
+text { font-family: 'Segoe UI', FreeSans, 'Helvetica Neue', Arial, sans-serif; }
+.bg { fill: #f8f9fb; stroke: #e1e5eb; }
+.col { font-size: 11px; font-weight: 600; letter-spacing: .05em; fill: #667385; }
+.bn .box { fill: #ffffff; stroke: #e1e5eb; stroke-width: 1.2; }
+.bn.t-store .box { fill: #e8f0fc; }
+.bn.legacy .box { fill: #f8f9fb; stroke: #c3cad4; stroke-dasharray: 5 4; }
+.bn.legacy .bn-t { fill: #3b4655; }
+.bn .band { fill: #1f5fbf; }
+.bn.undeclared .band { fill: #9a5600; }
+.bn.s-added .box { stroke: #157347; stroke-width: 1.8; } .bn.s-added .band { fill: #157347; }
+.bn.s-changed .box { stroke: #9a5600; stroke-width: 1.8; } .bn.s-changed .band { fill: #9a5600; }
+.bn.s-removed .box { stroke: #c4321c; stroke-dasharray: 5 4; fill: #fdecea; } .bn.s-removed .band { fill: #c4321c; }
+.bn-t { font-size: 13px; font-weight: 600; fill: #161c24; }
+.bn-s { font-size: 11.5px; fill: #667385; }
+.bn-p { font-size: 11.5px; fill: #3b4655; } .bn-p.code { font-family: Consolas, Inconsolata, 'DejaVu Sans Mono', monospace; } .bn-p.more { fill: #667385; }
+.bn-p.s-added { fill: #157347; font-weight: 600; } .bn-p.s-changed { fill: #9a5600; font-weight: 600; }
+.bn-p.s-removed { fill: #c4321c; text-decoration: line-through; }
+.be { fill: none; stroke: #667385; stroke-width: 1.4; opacity: .75; }
+.be.k-data { stroke: #1f5fbf; } .be.k-network { stroke: #9a5600; stroke-dasharray: 6 4; }
+.be.s-added { stroke: #157347; stroke-width: 2.2; opacity: 1; }
+.be.s-removed { stroke: #c4321c; stroke-dasharray: 5 4; opacity: 1; }
+.ar { fill: #667385; } .ar.k-data { fill: #1f5fbf; } .ar.k-network { fill: #9a5600; }
+.ar.s-added { fill: #157347; } .ar.s-removed { fill: #c4321c; } .ar.k-person { fill: #1f5fbf; }
+.halo { paint-order: stroke; stroke: #f8f9fb; stroke-width: 4px; stroke-linejoin: round; }
+.lg { font-size: 11.5px; fill: #667385; }
+.lg.s-added { fill: #157347; font-weight: 600; } .lg.s-changed { fill: #9a5600; font-weight: 600; }
+.lg.s-removed { fill: #c4321c; font-weight: 600; }
+.foot { font-size: 11.5px; fill: #3b4655; }
+.st .box { fill: #ffffff; stroke: #e1e5eb; stroke-width: 1.4; }
+.st.hi .box { fill: #e8f0fc; stroke: #1f5fbf; }
+.st-w { font-size: 13px; font-weight: 600; fill: #161c24; }
+.fl { fill: none; stroke: #667385; stroke-width: 1.4; } .fl.loop { stroke-dasharray: 4 4; }
+.fl.gate { stroke: #1f5fbf; stroke-dasharray: 2 4; opacity: .7; }
+.fl-note { font-size: 11.5px; fill: #667385; }
+.gate .box { fill: #e8f0fc; stroke: #1f5fbf; } .gate text { font-size: 12.5px; font-weight: 600; fill: #1f5fbf; }
+.exit { font-size: 12.5px; font-weight: 600; fill: #161c24; }
+.lane .box { fill: #ffffff; stroke: #e1e5eb; stroke-width: 1.2; }
+.lane.person .box { fill: #e8f0fc; stroke: #1f5fbf; }
+.life { stroke: #c9d0da; stroke-width: 1.2; stroke-dasharray: 3 4; }
+.msg { fill: none; stroke: #667385; stroke-width: 1.4; }
+.msg.frame { stroke: #1f5fbf; stroke-dasharray: 5 4; } .msg.person { stroke: #1f5fbf; stroke-width: 2; }
+.msg-t { font-size: 11.5px; fill: #3b4655; } .msg-t.frame { fill: #1f5fbf; } .msg-t.person { fill: #1f5fbf; font-weight: 600; }
+.num circle { fill: #667385; } .num.person circle { fill: #1f5fbf; }
+.num text { fill: #ffffff; font-size: 10px; font-weight: 700; }
+.note .box { fill: #fff3dd; stroke: #e9c98f; } .note text { font-size: 11.5px; fill: #9a5600; }
+</style>
+<defs><marker id="ar-call-same" class="ar k-call s-same" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z"/></marker><marker id="ar-data-same" class="ar k-data s-same" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z"/></marker></defs>
+<rect class="bg" x="0.5" y="0.5" width="1283" height="295" rx="10"/>
+<text class="col" x="14" y="18">QUESTIONS</text>
+<text class="col" x="278" y="18">HYPOTHESES</text>
+<text class="col" x="542" y="18">EXPERIMENTS</text>
+<text class="col" x="806" y="18">RESULTS</text>
+<text class="col" x="1070" y="18">CLAIMS</text>
+<path class="be k-call s-same" d="M1070,52 C1038,52 1038,128 1006,128 L806,128 C774,128 774,102 742,102 L542,102 C513,102 513,52 484,52" marker-end="url(#ar-call-same)"><title>C1 → H1</title></path>
+<path class="be k-call s-same" d="M1070,52 C1041,52 1041,157 1012,157" marker-end="url(#ar-call-same)"><title>C1 → R1</title></path>
+<path class="be k-call s-same" d="M542,52 C513,52 513,52 484,52" marker-end="url(#ar-call-same)"><title>E1 → H1</title></path>
+<path class="be k-call s-same" d="M806,52 C777,52 777,52 748,52" marker-end="url(#ar-call-same)"><title>E1.results → E1</title></path>
+<path class="be k-call s-same" d="M278,52 C249,52 249,52 220,52" marker-end="url(#ar-call-same)"><title>H1 → Q1</title></path>
+<path class="be k-call s-same" d="M278,128 C249,128 249,52 220,52" marker-end="url(#ar-call-same)"><title>H2 → Q1</title></path>
+<path class="be k-call s-same" d="M806,157 C777,157 777,52 748,52" marker-end="url(#ar-call-same)"><title>R1 → E1</title></path>
+<path class="be k-data s-same" d="M806,157 C774,157 774,104.5 742,104.5 L542,104.5 C513,104.5 513,52 484,52" marker-end="url(#ar-data-same)"><title>R1 → H1</title></path>
+<g class="bn t-component s-same" transform="translate(14,30)"><rect class="box" width="200" height="62" rx="8"/><text x="12" y="19" class="bn-t">Q1 How does batch size</text><text x="12" y="35" class="bn-t">change accuracy when th…</text><text x="12" y="51" class="bn-s">examples/batch-size/notes/ideas…</text><title>Q1 How does batch size change accuracy when there are under 10k examples?</title></g>
+<g class="bn t-component s-same new" transform="translate(278,30)"><rect class="box" width="200" height="62" rx="8"/><rect class="band" width="5" height="62" rx="2"/><text x="12" y="19" class="bn-t">H1 Smaller batches</text><text x="12" y="35" class="bn-t">generalise better on sm…</text><text x="12" y="51" class="bn-s">supported</text><title>H1 Smaller batches generalise better on small datasets</title></g>
+<g class="bn t-component s-same" transform="translate(278,106)"><rect class="box" width="200" height="62" rx="8"/><text x="12" y="19" class="bn-t">H2 Learning-rate warm-up</text><text x="12" y="35" class="bn-t">removes the gap</text><text x="12" y="51" class="bn-s">open</text><title>H2 Learning-rate warm-up removes the gap</title></g>
+<g class="bn t-component s-same" transform="translate(542,30)"><rect class="box" width="200" height="62" rx="8"/><text x="12" y="19" class="bn-t">E1 Batch 32 vs 512 on</text><text x="12" y="35" class="bn-t">small-8k</text><text x="12" y="51" class="bn-s">examples/batch-size/configs/e1.…</text><title>E1 Batch 32 vs 512 on small-8k</title></g>
+<g class="bn t-store s-same" transform="translate(806,30)"><rect class="box" width="200" height="91" rx="8"/><text x="12" y="19" class="bn-t">E1.results</text><text x="12" y="35" class="bn-s">examples/batch-size/out/e1.json</text><text x="14" y="53" class="bn-p s-same code">· acc.batch32 = 0.874</text><text x="14" y="68" class="bn-p s-same code">· acc.batch512 = 0.842</text><text x="14" y="83" class="bn-p s-same code">· epochs = 30</text><title>E1.results</title></g>
+<g class="bn t-store s-same" transform="translate(806,135)"><rect class="box" width="200" height="77" rx="8"/><text x="12" y="19" class="bn-t">R1 Batch 32 beats 512 by</text><text x="12" y="35" class="bn-t">3.2 points</text><text x="12" y="51" class="bn-s">examples/batch-size/notes/resul…</text><text x="14" y="69" class="bn-p s-same code">· gap = 0.032</text><title>R1 Batch 32 beats 512 by 3.2 points</title></g>
+<g class="bn t-component s-same" transform="translate(1070,30)"><rect class="box" width="200" height="62" rx="8"/><text x="12" y="19" class="bn-t">C1 Small batches give</text><text x="12" y="35" class="bn-t">better accuracy on smal…</text><text x="12" y="51" class="bn-s">2 sources</text><title>C1 Small batches give better accuracy on small datasets</title></g>
+<rect x="16" y="246" width="14" height="12" rx="2" fill="#ffffff" stroke="#e1e5eb"/><rect x="16" y="246" width="4" height="12" rx="1" fill="#1f5fbf"/>
+<text x="36" y="256" class="lg">supported</text>
+<path class="be k-call" d="M109.9,252 L129.9,252" style="opacity:1"/>
+<text x="135.9" y="256" class="lg">links</text>
+<path class="be k-data" d="M184.9,252 L204.9,252" style="opacity:1"/>
+<text x="210.9" y="256" class="lg">supports</text>
+<text class="foot" x="16" y="282">1 warning: H2 is open and no experiment tests it</text>
+</svg>

research_diff-0.1.0/examples/batch-size/configs/e1.yaml

@@ -0,0 +1,10 @@
+# Batch 32 against batch 512 on the 8k-example split.
+model: resnet18
+dataset: small-8k
+batch_sizes: [32, 512]
+
+research:
+  id: E1
+  title: Batch 32 vs 512 on small-8k
+  tests: [H1]
+  results: ../out/e1.json

research_diff-0.1.0/examples/batch-size/notes/ideas.md

@@ -0,0 +1,15 @@
+# Does batch size matter on small datasets?
+
+## Q1: How does batch size change accuracy when there are under 10k examples?
+
+## H1: Smaller batches generalise better on small datasets
+
+answers: Q1
+status: supported
+
+## H2: Learning-rate warm-up removes the gap
+
+answers: Q1
+status: open
+
+The idea: the gap may be an optimisation artefact rather than a generalisation one.

research_diff-0.1.0/examples/batch-size/notes/results.md

@@ -0,0 +1,7 @@
+# Results
+
+## R1: Batch 32 beats 512 by 3.2 points
+
+of: E1
+supports: H1
+metrics: gap=0.032

research_diff-0.1.0/examples/batch-size/out/e1.json

@@ -0,0 +1 @@
+{"acc": {"batch32": 0.874, "batch512": 0.842}, "epochs": 30}

research_diff-0.1.0/examples/batch-size/paper/main.tex

@@ -0,0 +1,7 @@
+\section{Results}
+
+% C1: Small batches give better accuracy on small datasets
+% relies on: H1, R1
+% expects: E1.results acc.batch32 > 0.85
+On the 8k split, batch 32 reaches 87.4\% against 84.2\% for batch 512, in line with
+earlier work \cite{keskar2017large,masters2018revisiting}.

research_diff-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "research-diff"
+version = "0.1.0"
+description = "Maps your research from its notes, experiment configs, results and paper (questions, hypotheses, experiments, results, claims) and shows what each iteration changed. Built for exploring ideas with AI coding agents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "simplifiedmachine" }]
+keywords = ["research", "experiment-tracking", "hypotheses", "reproducibility", "ai-agents", "claude-code", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering",
+]
+# Its pictures, snapshots and live page are system-diff's (same author, no dependencies of its own), pinned.
+dependencies = ["system-diff==0.1.0"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.10"]
+dev = ["pytest>=8", "mcp>=1.10"]
+
+[project.urls]
+Homepage = "https://github.com/simplifiedmachine/research-diff"
+Documentation = "https://github.com/simplifiedmachine/research-diff/wiki"
+
+[project.scripts]
+research-diff = "research_diff.cli:main"
+resdiff = "research_diff.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/research_diff"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

research_diff-0.1.0/research-diff.toml

@@ -0,0 +1,8 @@
+# research-diff on its own example project: the README's map is drawn from examples/.
+notes = ["examples/**/*.md"]
+configs = ["examples/**/*.yaml", "examples/**/*.json"]
+scripts = ["examples/**/*.py"]
+paper = ["examples/**/*.tex"]
+
+[readme]
+image = "https://raw.githubusercontent.com/simplifiedmachine/research-diff/main/docs/research.svg"  # shows on PyPI too

research_diff-0.1.0/src/research_diff/__init__.py

@@ -0,0 +1,2 @@
+"""research-diff: your research as a map, and what each iteration changed in it."""
+__version__ = "0.1.0"

research_diff-0.1.0/src/research_diff/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())