lab-kit-cli 1.0.1__tar.gz → 1.0.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/CHANGELOG.md +63 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/PKG-INFO +1 -1
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/docs/model.md +81 -8
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/pyproject.toml +1 -1
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/skills/lab-set-up/SKILL.md +4 -1
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/skills/lab-work/SKILL.md +10 -4
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/__init__.py +1 -1
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/checks.py +33 -16
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/history.py +36 -2
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/record.py +89 -12
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/runs.py +3 -1
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/site.py +21 -3
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/views.py +25 -2
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/write.py +2 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_held.py +174 -1
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_integrity.py +23 -0
- lab_kit_cli-1.0.3/tests/test_needs.py +148 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_refusals.py +1 -1
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_site.py +25 -3
- lab_kit_cli-1.0.3/tests/test_vocabulary.py +116 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/.github/workflows/ci.yml +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/.github/workflows/policy.yml +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/.github/workflows/release.yml +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/.gitignore +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/AGENTS.md +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/CLAUDE.md +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/CONTRIBUTING.md +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/LICENSE +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/README.md +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/agents/reviewer.md +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/method/METHOD.md +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/skills/lab-review/SKILL.md +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/skills/lab-talk/SKILL.md +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/cli.py +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/supervise.py +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_flow.py +0 -0
- {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tools/import_run.py +0 -0
|
@@ -1,5 +1,68 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.0.3
|
|
4
|
+
|
|
5
|
+
A word is now defined in one place, `GLOSSARY.md`. Before, the glossary and the goal's Vocabulary
|
|
6
|
+
both said what a word means, and the two could drift. The skills `lab-work` and `lab-set-up` changed:
|
|
7
|
+
run `lab init` in a lab after upgrading, or `lab check` reports that they differ from the installed
|
|
8
|
+
kit. Change the goal's Vocabulary to names, too: see below.
|
|
9
|
+
|
|
10
|
+
- A glossary entry may carry two more lines beside `- code:`. `- avoid: gate, filter, policy` lists
|
|
11
|
+
the words not to use for the thing; `- see: entries/kna-gate` (or a page of a library the charter
|
|
12
|
+
names, such as `pier-folio:/content/concepts/lora/`) names a page that explains the concept.
|
|
13
|
+
`lab define` prints both, and the glossary page shows the avoid words in small type and the page as a
|
|
14
|
+
link. The hover on a term stays the definition alone. `lab check` checks a `see` as it checks a
|
|
15
|
+
card's `see:`. It does not flag avoid words used in cards: a word to avoid for one thing is often right
|
|
16
|
+
for another.
|
|
17
|
+
- The goal's Vocabulary is a list of names only (`- field`). The goal's page and `lab show` draw
|
|
18
|
+
each with its glossary definition. `lab check` reports a name that is not a glossary term. A goal
|
|
19
|
+
written the old way (`- word: meaning`) still shows the glossary's definition, never the card's, and
|
|
20
|
+
`lab check` reports it: list the name only, and add the term to the glossary if it is missing there.
|
|
21
|
+
An existing lab must change its goal's Vocabulary to names.
|
|
22
|
+
|
|
23
|
+
## 1.0.2
|
|
24
|
+
|
|
25
|
+
One defect found while rehearsing a real lab, four follow-ups from 1.0.1, and three larger word
|
|
26
|
+
budgets. The skill `lab-work` changed with the budgets: run `lab init` in a lab after upgrading, or
|
|
27
|
+
`lab check` reports that the skill differs from the installed kit.
|
|
28
|
+
|
|
29
|
+
- A step may need a step that sits later in the tree, such as a build under the second question
|
|
30
|
+
that needs a reading under the third. States used to be worked out in the order of the cards, so
|
|
31
|
+
the earlier step never saw that the later one was done: it stayed under "Not yours to move yet",
|
|
32
|
+
waiting on a step that was done, and `lab lock` and `lab run` refused it. Each step's state is now
|
|
33
|
+
worked out after everything it needs, wherever that sits. `lab now`, `lab show`, `lab brief` and
|
|
34
|
+
the site agree, since they read the same states.
|
|
35
|
+
- Steps that need each other in a circle were already a problem in `lab check`. Now none of them
|
|
36
|
+
moves until the circle is broken, even when one of them is done, and each says which need leads
|
|
37
|
+
back to it.
|
|
38
|
+
- Rows that a committed review passed stay. A reviewed `results.tsv` could be emptied together with
|
|
39
|
+
the card's Found and Means, committed, and later filled with other rows and reviewed again, with
|
|
40
|
+
`lab check` sound at every step. Once a results review that passed is committed with the rows it
|
|
41
|
+
read, those rows are held, whatever the card and the file say later. A draft row committed after
|
|
42
|
+
a review, which that review never read, may still be corrected.
|
|
43
|
+
- A step that needs one that is dropped or replaced says so in what it waits on, with what to do:
|
|
44
|
+
remove the need or replace it. A need that names nothing in the lab, or something that is not a
|
|
45
|
+
step, now holds the step in `lab lock` and `lab run`, as `lab check` already reported it.
|
|
46
|
+
- A `.pyc` file in `plan/` outside `__pycache__` is refused by `lab lock` and `lab run` and reported
|
|
47
|
+
by `lab check`, as a link is: Python would import it, and the plan's hash does not cover it.
|
|
48
|
+
- `lab check` says in a note when the repository is a shallow clone, and fails with `--strict`: the
|
|
49
|
+
history check needs every commit, and CI should fetch all of the history (`fetch-depth: 0`). The
|
|
50
|
+
model also says that the history read is that of the record under the lab's root as it is now,
|
|
51
|
+
so moving the root inside the repository starts again what is held.
|
|
52
|
+
- A plan that 1.0.0 locked or ran while a `__pycache__` sat in `plan/` verifies again. 1.0.0 counted
|
|
53
|
+
those files in the plan's hash and 1.0.1 does not, so such a record could never match. When a
|
|
54
|
+
hash of `plan/` does not match and the experiment's lock was made by 1.0.0, the folder is hashed
|
|
55
|
+
once more the way 1.0.0 did before a change is reported. It applies to no other lock, and only
|
|
56
|
+
while the cache files are still there as they were.
|
|
57
|
+
- `lab show <experiment>` says of each run how many files it holds, how many at the top of its
|
|
58
|
+
folder and how many under each folder there. It used to list ten files and leave out `work/`, so
|
|
59
|
+
a run whose output was all in `work/` looked nearly empty.
|
|
60
|
+
- Three word budgets are larger, because real cards were hitting them and ending in fragments: an
|
|
61
|
+
experiment's Found goes from 130 words to 180 and its Means from 90 to 150, and a question's So
|
|
62
|
+
far from 120 to 180. A budget is a ceiling against sprawl. If a card needs its last words cut
|
|
63
|
+
into fragments to fit, it is saying too much for one slot or the budget is wrong, and full
|
|
64
|
+
sentences win.
|
|
65
|
+
|
|
3
66
|
## 1.0.1
|
|
4
67
|
|
|
5
68
|
Three defects found by moving a real repository to 1.0.0, and one message.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: lab-kit-cli
|
|
3
|
-
Version: 1.0.
|
|
3
|
+
Version: 1.0.3
|
|
4
4
|
Summary: A research lab's record, its method, and the command that keeps both.
|
|
5
5
|
Project-URL: Homepage, https://github.com/pierg/lab-kit
|
|
6
6
|
Project-URL: Issues, https://github.com/pierg/lab-kit/issues
|
|
@@ -32,7 +32,9 @@ leads to is complete: it never points at something it does not explain ("the sev
|
|
|
32
32
|
reproduction's setting", "our loop") without saying what that is in the same place. An experiment
|
|
33
33
|
names each arm and says what it is. A term is explained in the sentence that first uses it; the
|
|
34
34
|
glossary is a second chance, not the explanation. A slot may hold paragraphs and a list when that
|
|
35
|
-
is clearer than one long sentence. The word budgets are ceilings against sprawl, not targets.
|
|
35
|
+
is clearer than one long sentence. The word budgets are ceilings against sprawl, not targets. If a
|
|
36
|
+
card needs its last words cut into fragments to fit, the card is saying too much for one slot or
|
|
37
|
+
the budget is wrong, and full sentences win.
|
|
36
38
|
|
|
37
39
|
A run's id is `<date>-<time>_<experiment>_<four random characters>`, for example
|
|
38
40
|
`20261110-1432_G1.Q2.3_k7f2`. It sorts by time, and two machines starting runs in the same minute cannot
|
|
@@ -149,6 +151,19 @@ Each arrow is a command that refuses when the step before it is missing. You see
|
|
|
149
151
|
`lab now` and `lab check` say which locks and lists of runs are not committed yet. With no commit
|
|
150
152
|
at all nothing is held, and `lab check` says that too; `--strict` turns each of these into a
|
|
151
153
|
failure.
|
|
154
|
+
**Reviewed rows stay.** The rows of `results.tsv` may change until a review passes them. Once a
|
|
155
|
+
results review that passed is committed together with the rows it read, those rows stay, each as
|
|
156
|
+
it was, whatever happens to the card and to the reviews after it. Emptying the file or removing it
|
|
157
|
+
together with Found and Means, and filling it later with other rows for a new review, is a
|
|
158
|
+
problem `lab check` reports at every step: a different result is a new experiment. A review is
|
|
159
|
+
bound to the rows it read by its `of`, so only those are held: a draft row committed after a
|
|
160
|
+
review, which that review never read, may still be corrected before the next review reads it.
|
|
161
|
+
**The history that is read.** The check reads the history of the record under the lab's root as
|
|
162
|
+
that root is now. Moving the lab's root inside its repository, or to another repository, starts
|
|
163
|
+
again what is held: what was committed under the old root is not compared. And it needs the
|
|
164
|
+
repository's full history. A shallow clone holds only its last commits, so against it almost
|
|
165
|
+
nothing is held: `lab check` says so in a note, and fails with `--strict`. CI fetches all of the
|
|
166
|
+
history before it checks (`fetch-depth: 0` in `actions/checkout`).
|
|
152
167
|
**Where the record is.** The check reads the history of the lab's own record and of nothing else:
|
|
153
168
|
`log.md` and `resources.toml` at the lab's root, `decisions/D<n>-<name>.md`, and each experiment's
|
|
154
169
|
`lock.json`, `runs.tsv`, `results.tsv` and `reviews.tsv` in its folder,
|
|
@@ -265,7 +280,10 @@ that resource, under `about:`.
|
|
|
265
280
|
## 5. What the agent uses
|
|
266
281
|
|
|
267
282
|
- **To look:** `lab now`, `lab show <id or path>`, `lab brief <question>`, `lab since`, `lab define <term>`. Each shows one level,
|
|
268
|
-
so the agent reads a card before it opens a file.
|
|
283
|
+
so the agent reads a card before it opens a file. Of each run, `lab show <experiment>` says how
|
|
284
|
+
many files it holds and where: how many at the top of its folder, and how many under each folder
|
|
285
|
+
there, `work/` included. It lists none of them, so a run whose output is all in `work/` does not
|
|
286
|
+
look empty.
|
|
269
287
|
- **To write:** `lab new` (a goal, a question, an experiment, a build, a reading, a decision),
|
|
270
288
|
`lab log`, `lab decide`, `lab answer`.
|
|
271
289
|
- **To be seen:** `lab log <id> doing "<what>" "<why now>"` whenever it starts on a card. It is the
|
|
@@ -307,7 +325,7 @@ Seven rules:
|
|
|
307
325
|
Never record a decision that was not discussed with them.
|
|
308
326
|
7. Say what you are on. When you start on a card, log what you are doing and why now.
|
|
309
327
|
|
|
310
|
-
`lab check` holds what can be held mechanically: ids and links, a title and a description on every
|
|
328
|
+
`lab check` holds what can be held mechanically: ids and links, the goal's vocabulary being terms of the glossary, a title and a description on every
|
|
311
329
|
card, short cards that write only their own front matter, a test on every line, a reason on every
|
|
312
330
|
replacement, unchanged locks, sealed runs, results that still re-derive and were reviewed, use inside
|
|
313
331
|
the resources' amounts, a decision behind every goal, question and metered amount, an experiment
|
|
@@ -317,7 +335,7 @@ file that is not text) is a problem it reports; no command stops on it.
|
|
|
317
335
|
|
|
318
336
|
`lab check` runs the command of every row in every `results.tsv`, as a shell command, each for at
|
|
319
337
|
most `rederive_timeout` seconds (`lab.toml`, 120 unless set). Run it only on a lab you trust, as
|
|
320
|
-
you would its code; `--no-rederive` runs none of them. Where the lab has no commit, the store
|
|
338
|
+
you would its code; `--no-rederive` runs none of them. Where the lab has no commit or its repository is a shallow clone, the store
|
|
321
339
|
is not mounted, or another library that a card's `see:` points into is not on the machine, the check
|
|
322
340
|
says in a note what it could not check and still passes; with `--strict` that is a failure, which is
|
|
323
341
|
what CI wants.
|
|
@@ -369,7 +387,8 @@ resource. Nothing on it is static text except one line per goal.
|
|
|
369
387
|
**An example on every question.** A question's page carries one case, step by step, as a numbered
|
|
370
388
|
list that says who does what: the user, the agent, the tools, the gate, the scorer. A real episode
|
|
371
389
|
where one exists, and said to be only the flow where none does. The goal's page says once who plays
|
|
372
|
-
each role, states the design before the approximation, and
|
|
390
|
+
each role, states the design before the approximation, and lists its vocabulary: the words every card
|
|
391
|
+
uses the same way, each drawn with the glossary's definition.
|
|
373
392
|
|
|
374
393
|
**What was dropped** stays in the record: a dropped goal or question keeps its card and its page,
|
|
375
394
|
and leaves Now, the rail and the graph.
|
|
@@ -431,9 +450,9 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
|
|
|
431
450
|
|
|
432
451
|
| Card | Front matter | Slots (word budget) |
|
|
433
452
|
| --- | --- | --- |
|
|
434
|
-
| `goal.md` | `title:`, `from:` (its decision); `reached: true`; `dropped: <why>` | description (70), Claim (90), Example: the idea in one case, from the reader's own domain (260), Approach: the design, how this lab approximates it, and where it knowingly differs (340), Roles: a list, `- <role>: <who plays it and what it does>` (170), Vocabulary: a list, `- <
|
|
435
|
-
| `question.md` | `title:` (a short name), `asks:` (the question in full), `from:`, `needs:`; `dropped: <why>`; `answer:` and `answered:` are written by `lab answer` | description: why we ask (130), How we would know (150), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (
|
|
436
|
-
| `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (70), Compares: the comparison in a sentence (80), Arms (260), Cases (100), Confirmed if (150), Refuted if (110), Outcomes (200), Limits (120), Found (
|
|
453
|
+
| `goal.md` | `title:`, `from:` (its decision); `reached: true`; `dropped: <why>` | description (70), Claim (90), Example: the idea in one case, from the reader's own domain (260), Approach: the design, how this lab approximates it, and where it knowingly differs (340), Roles: a list, `- <role>: <who plays it and what it does>` (170), Vocabulary: a list of names only, `- <term>`, the few words every card uses the same way; each is a term of `GLOSSARY.md`, which defines it (260) |
|
|
454
|
+
| `question.md` | `title:` (a short name), `asks:` (the question in full), `from:`, `needs:`; `dropped: <why>`; `answer:` and `answered:` are written by `lab answer` | description: why we ask (130), How we would know (150), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (180) |
|
|
455
|
+
| `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (70), Compares: the comparison in a sentence (80), Arms (260), Cases (100), Confirmed if (150), Refuted if (110), Outcomes (200), Limits (120), Found (180), Means (150) |
|
|
437
456
|
| `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
|
|
438
457
|
| `build.md` | `title:`, `needs:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
|
|
439
458
|
| `D<n>-<slug>.md` | `title:`, `about:` (the goals, questions, experiments or resources it concerns), `date:`, `holds:`; `decided: {date, with}` is written by `lab decide` | Seen (120), Options: a list, one option an item (200), Recommendation (80), Decided (120) |
|
|
@@ -450,6 +469,36 @@ as in CI, which checks out the lab alone, the page cannot be looked for: that is
|
|
|
450
469
|
failure only with `--strict`. When the folder is there and the page is not, or the charter names no
|
|
451
470
|
such library, it is a problem.
|
|
452
471
|
|
|
472
|
+
**The glossary** is `GLOSSARY.md`, the only place a word is defined. A group is a `# Group` heading
|
|
473
|
+
and a term a `## Term` heading under it, followed by its definition as a paragraph and these optional
|
|
474
|
+
lines, each `- key: value`:
|
|
475
|
+
|
|
476
|
+
```
|
|
477
|
+
## Guard
|
|
478
|
+
The part that reads every call and refuses the ones the contract forbids.
|
|
479
|
+
- code: kna.gate:Guard
|
|
480
|
+
- avoid: gate, filter, policy
|
|
481
|
+
- see: entries/kna-gate
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
`code:` is where the term is in the code. `avoid:` lists, separated by commas, the words not to use
|
|
485
|
+
for this thing. `see:` names a page that explains the concept: a page of the lab's own library
|
|
486
|
+
(`entries/kna-gate`) or of a library the charter names (`pier-folio:/content/concepts/lora/`), the
|
|
487
|
+
same targets a card's `see:` takes. `lab define <term>` prints all of it. The glossary page shows the
|
|
488
|
+
definition, the code, the page as a link and the avoid words in small type; the hover on a term in
|
|
489
|
+
prose is the definition alone.
|
|
490
|
+
|
|
491
|
+
A word is defined once, in the glossary. A card that needs a word adds it there first, then uses it;
|
|
492
|
+
no card defines a word of its own. A concept that is not this lab's own (a method, a paper's idea) gets
|
|
493
|
+
a one-line entry and a `see:` link to the page that explains it, not a new explanation. The goal's
|
|
494
|
+
Vocabulary lists terms by name, and the goal's page and `lab show` draw each with the glossary's
|
|
495
|
+
definition and avoid words. `lab check` holds this: a name in Vocabulary that is not a term of the
|
|
496
|
+
glossary is a problem, and so is an item written with a meaning (`- word: what it means`): the part
|
|
497
|
+
before the colon is taken as the name, the glossary's text is what is shown, and the card must list the
|
|
498
|
+
name only. It checks an entry's `see:` as it checks a card's, including the note, and no failure, when
|
|
499
|
+
the other library is not on the machine. It does not look for avoid words in cards: a word to avoid for
|
|
500
|
+
one thing is often the right word for another, so `avoid:` is for the writer and the reviewer to read.
|
|
501
|
+
|
|
453
502
|
**An arm** is a list item under Arms: its name, a colon, and what it is, so that a reader who has
|
|
454
503
|
never seen it knows what was run.
|
|
455
504
|
|
|
@@ -518,6 +567,16 @@ it imports a script, which is no part of the plan: a folder named `__pycache__`
|
|
|
518
567
|
it, and any file whose name ends in `.pyc`, wherever it sits. Nothing else is left out; a hidden
|
|
519
568
|
file is hashed like any other.
|
|
520
569
|
|
|
570
|
+
One exception, for what lab-kit 1.0.0 made. That version did hash those files, so a plan locked or
|
|
571
|
+
run while a `__pycache__` sat in `plan/` holds a hash that counts them. When a hash of `plan/` held
|
|
572
|
+
by a lock or a run does not match and the experiment's lock says `"kit": "1.0.0"`, the folder is
|
|
573
|
+
hashed once more the way 1.0.0 did, those files included, before a change is reported. It applies
|
|
574
|
+
to no other lock, and it verifies only while those files are still there as they were.
|
|
575
|
+
|
|
576
|
+
A `.pyc` file in `plan/` that is not inside a `__pycache__` is refused, as a link is: Python would
|
|
577
|
+
import it in place of a script, and no hash covers it. `lab lock` and `lab run` refuse the plan and
|
|
578
|
+
`lab check` reports it. Under a lock that 1.0.0 made, whose hash did count such a file, it stays.
|
|
579
|
+
|
|
521
580
|
**`runs.tsv`**, beside the lock and in git, is written by `lab run` and by the run as it ends: `run`
|
|
522
581
|
(its id), `kind` (run, trial), `what` (started, ended, lost), `at`, on the ended row `exit` and `seal`,
|
|
523
582
|
and on a lost row `used` (`{"<resource>": <amount>}`, or empty) and `note` (why it is lost). When a
|
|
@@ -537,3 +596,17 @@ starting on and why now. A line written before the kit kept the time has none.
|
|
|
537
596
|
open, then yes or no; a page calls an open question with nothing under it "not started". A build is in
|
|
538
597
|
progress once the log has a line about it, and built once it names its commits. An experiment whose
|
|
539
598
|
results review failed shows as review failed until it is replaced or dropped.
|
|
599
|
+
|
|
600
|
+
**What a step needs.** `needs:` on an experiment, a build or a reading names other steps, anywhere in
|
|
601
|
+
the tree: under its own question or another, before it or after it. A step is not the agent's to move
|
|
602
|
+
while one it needs is neither done nor built, and `lab lock` and `lab run` refuse it until then. Each
|
|
603
|
+
step's state is worked out after the state of everything it needs, wherever that sits, so the order
|
|
604
|
+
of the cards changes nothing: a build under the second question that needs a reading under the third
|
|
605
|
+
moves as soon as that reading is done. Every view says the same: `lab now`, `lab show`, `lab brief`,
|
|
606
|
+
and the site's pages and rail. Steps that need each other in a circle are a problem `lab check`
|
|
607
|
+
reports. Until the circle is broken none of them moves, whatever the others' states, and each says
|
|
608
|
+
which of its needs leads back to it. A step that needs one that is dropped or replaced would wait
|
|
609
|
+
for ever, so what it waits on says so, and says what to do: remove the need or replace it. A need
|
|
610
|
+
that names nothing in the lab, or something that is not a step, holds the step in `lab lock` and
|
|
611
|
+
`lab run` as `lab check` reports it. A question's `needs:` names the questions it builds on, for its
|
|
612
|
+
briefing; it changes no state.
|
|
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
|
|
|
5
5
|
[project]
|
|
6
6
|
dynamic = ["readme"]
|
|
7
7
|
name = "lab-kit-cli"
|
|
8
|
-
version = "1.0.
|
|
8
|
+
version = "1.0.3"
|
|
9
9
|
description = "A research lab's record, its method, and the command that keeps both."
|
|
10
10
|
license = "MIT"
|
|
11
11
|
authors = [{ name = "Piergiuseppe Mallozzi" }]
|
|
@@ -37,7 +37,10 @@ You set the lab up in one discussion with the operator, so that everything it se
|
|
|
37
37
|
9. Fill `lab.toml` (`code` for the code repository, `store` if the runs live elsewhere) and the
|
|
38
38
|
local rules in `AGENTS.md`.
|
|
39
39
|
10. Start `GLOSSARY.md`: each term the cards use that an outsider would not know, one sentence, with
|
|
40
|
-
its name in the code when it has one
|
|
40
|
+
its name in the code when it has one (`- code: module:Name`), the words not to use for it
|
|
41
|
+
(`- avoid: a, b`) and a page that explains it (`- see: <page>`) when there is one. The glossary is the
|
|
42
|
+
only place a word is defined: the goal's Vocabulary lists names, and a card that needs a word adds it
|
|
43
|
+
here first.
|
|
41
44
|
11. The site: the lab's `docs/` folder is a folio library whose charter lists `lab_kit.site` under
|
|
42
45
|
`views:`. Set it up with folio's own skill if it is not there.
|
|
43
46
|
|
|
@@ -36,14 +36,20 @@ The operator reads every card on the site, usually days later and without you. W
|
|
|
36
36
|
- A paper, a method or a tool the reader may not know gets a few words saying what it is, and a
|
|
37
37
|
link where it is first named: `[PISmith](pier-folio:/content/readings/...)` for a page of a
|
|
38
38
|
library the charter names, or a web address. Put the same page under `see:`.
|
|
39
|
-
-
|
|
40
|
-
|
|
39
|
+
- A word is defined once, in `GLOSSARY.md`, and nowhere else. Use the goal's vocabulary: the goal's
|
|
40
|
+
card lists, by name only (`- field`), the few words the lab uses for its own things; use those words,
|
|
41
|
+
the same way, on every card, and read a term's `avoid:` words as the ones not to use for it. When a
|
|
42
|
+
card needs a new word, add it to the glossary first, then list it on the goal if every card uses it.
|
|
43
|
+
A generic concept that is not this lab's own gets a one-line glossary entry and a `- see:` link to the
|
|
44
|
+
page that explains it, not a new explanation.
|
|
41
45
|
- Say the design before the approximation: what the idea wants, then how this lab builds it and
|
|
42
46
|
where it knowingly differs. A shortcut of the implementation is never the definition.
|
|
43
47
|
- Say what is measured and what is your reading of it, in so many words.
|
|
44
48
|
- Use a list when the content is a list (arms, options, steps), and a second paragraph when one
|
|
45
49
|
sentence is carrying too much. The word budgets are ceilings, not targets: short is good only
|
|
46
|
-
while nothing is missing.
|
|
50
|
+
while nothing is missing. A budget is there against sprawl. If a card needs its last words cut
|
|
51
|
+
into fragments to fit, the card is saying too much for one slot or the budget is wrong, and full
|
|
52
|
+
sentences win.
|
|
47
53
|
- Read the card as someone who was not there. If a question comes to mind, the card answers it.
|
|
48
54
|
|
|
49
55
|
## When to open a decision
|
|
@@ -206,7 +212,7 @@ what should come next: open a decision.
|
|
|
206
212
|
- Never write that the operator decided something outside a decision recorded with `lab decide` (the
|
|
207
213
|
lab-talk skill).
|
|
208
214
|
- Open `plan/` and `runs/` only for the experiment you are working on.
|
|
209
|
-
- A term an outsider would not know goes in `GLOSSARY.md`, once, and is used the same way everywhere.
|
|
215
|
+
- A term an outsider would not know goes in `GLOSSARY.md`, once, and is used the same way everywhere. A card never defines a word itself, and the goal's Vocabulary holds names, not meanings.
|
|
210
216
|
|
|
211
217
|
## Before you stop
|
|
212
218
|
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
"""lab-kit: a research lab's record, its method, and the command that keeps both."""
|
|
2
|
-
__version__ = "1.0.
|
|
2
|
+
__version__ = "1.0.3"
|
|
@@ -27,6 +27,22 @@ def run(lab, rederive=True):
|
|
|
27
27
|
unchecked = True
|
|
28
28
|
|
|
29
29
|
absent = {} # the libraries the charter names whose folder is not on this machine
|
|
30
|
+
|
|
31
|
+
def see(where, page, who=""):
|
|
32
|
+
"""A page a card's `see:` or a glossary entry's `- see:` names is there."""
|
|
33
|
+
if ":" in str(page): # a page of another library the charter names, such as background reading
|
|
34
|
+
from . import site
|
|
35
|
+
name, _, path = str(page).partition(":")
|
|
36
|
+
lib = site.libraries(lab).get(name)
|
|
37
|
+
if not lib:
|
|
38
|
+
bad("links", where, f"{who}see names {page}, which is not a page of a library the charter names")
|
|
39
|
+
elif not os.path.isdir(lib["path"]): # the other library is not on this machine, as in CI: nothing to look in
|
|
40
|
+
absent.setdefault(name, lib["path"])
|
|
41
|
+
elif not os.path.exists(os.path.join(lib["path"], path.lstrip("/"))):
|
|
42
|
+
bad("links", where, f"{who}see names {page}, and the library {name} holds no such page")
|
|
43
|
+
elif not os.path.exists(os.path.join(library, str(page).split("#")[0], "index.html")):
|
|
44
|
+
bad("links", where, f"{who}see names the page {page}, which is not in the library")
|
|
45
|
+
|
|
30
46
|
# cards: each has its slots, stays short, and writes only what is its to write
|
|
31
47
|
for n in lab.goals + lab.questions + lab.items + lab.decisions:
|
|
32
48
|
try:
|
|
@@ -51,20 +67,18 @@ def run(lab, rederive=True):
|
|
|
51
67
|
if n["type"] in ("goal", "question") and nodes.get(str(n.get("from")), {}).get("type") != "decision":
|
|
52
68
|
bad("links", n["path"], f"`from:` names the decision it came out of; {n.get('from')!r} is not one")
|
|
53
69
|
for page in n.get("see") or []:
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
elif not os.path.exists(os.path.join(library, str(page).split("#")[0], "index.html")):
|
|
65
|
-
bad("links", n["path"], f"see names the page {page}, which is not in the library")
|
|
70
|
+
see(n["path"], page)
|
|
71
|
+
if n["type"] == "goal": # the words a goal lists are names; GLOSSARY.md is the only place a word is defined
|
|
72
|
+
for w in lab.vocabulary(n):
|
|
73
|
+
if not w["entry"]:
|
|
74
|
+
bad("cards", n["path"], f"Vocabulary lists {w['name']!r}, which is not a term in GLOSSARY.md: add it there first, and list the name only")
|
|
75
|
+
elif w["old"]:
|
|
76
|
+
bad("cards", n["path"], f"Vocabulary lists {w['name']!r} with a meaning: list the name only, `- {w['name']}`; GLOSSARY.md defines it")
|
|
77
|
+
for g in lab.glossary:
|
|
78
|
+
if g["see"]:
|
|
79
|
+
see("GLOSSARY.md", g["see"], f"{g['term']}: ")
|
|
66
80
|
for name, path in sorted(absent.items()):
|
|
67
|
-
notes.append(f"the library {name} is not here ({path}): the pages cards name in it under `see:` could not be checked here")
|
|
81
|
+
notes.append(f"the library {name} is not here ({path}): the pages cards and the glossary name in it under `see:` could not be checked here")
|
|
68
82
|
unchecked = True
|
|
69
83
|
for d in {os.path.dirname(x["path"]) for x in lab.items}:
|
|
70
84
|
if sum(os.path.exists(os.path.join(root, d, f"{kind}.md")) for kind in R.STEPS) > 1:
|
|
@@ -150,6 +164,9 @@ def run(lab, rederive=True):
|
|
|
150
164
|
links = R.symlinks(os.path.join(d, "plan"))
|
|
151
165
|
if links:
|
|
152
166
|
bad("locks", p, f"plan/ holds a link, {links[0]}: what a link points at is not in plan/ and is not pinned")
|
|
167
|
+
stray = R.compiled(os.path.join(d, "plan")) if (x["lock"] or {}).get("kit") != "1.0.0" else [] # 1.0.0 hashed such a file with the plan
|
|
168
|
+
if stray:
|
|
169
|
+
bad("locks", p, f"plan/ holds a compiled file outside __pycache__, {stray[0]}: Python would import it, and a `.pyc` is not pinned")
|
|
153
170
|
if x["lock"]:
|
|
154
171
|
if lab.nodes[x["question"]]["state"] == "under discussion":
|
|
155
172
|
bad("locks", p, f"is locked under {x['question']}, whose decision is not settled")
|
|
@@ -162,13 +179,13 @@ def run(lab, rederive=True):
|
|
|
162
179
|
bad("locks", p, "is locked with no refuted-if line")
|
|
163
180
|
if any(lab.metered(r) for r in x["uses"]) and not any(r.get("stage") == "plan" and r.get("verdict") == "pass" for r in x["reviews"]):
|
|
164
181
|
bad("locks", p, "uses a metered resource and was locked with no passed review of its plan")
|
|
165
|
-
if x["finished"] and x["finished"].get("plan") and x["finished"]["plan"]
|
|
182
|
+
if x["finished"] and x["finished"].get("plan") and not lab.plan_is(x, x["finished"]["plan"], x["finished"]["how"]):
|
|
166
183
|
bad("locks", p, f"plan/ changed after {x['finished']['id']}, the run its results come from; the apparatus of a finished run stays as it ran")
|
|
167
184
|
ran = [r for r in x["runs"] if not r["missing"]]
|
|
168
|
-
if ran and x["lock"].get("plan") and ran[0]["how"] == x["lock"]["hash"] and ran[0].get("plan")
|
|
185
|
+
if ran and x["lock"].get("plan") and ran[0]["how"] == x["lock"]["hash"] and lab.plans_differ(x, ran[0].get("plan"), x["lock"]["plan"], ran[0]["how"]) and not R.flat(ran[0].get("changed") or ""):
|
|
169
186
|
bad("runs", ran[0]["dir"], "ran a plan/ that differs from the one that was locked and does not say what changed and why")
|
|
170
187
|
for before, after in zip(ran, ran[1:]):
|
|
171
|
-
if before["how"] == after["how"] and before.get("plan")
|
|
188
|
+
if before["how"] == after["how"] and lab.plans_differ(x, before.get("plan"), after.get("plan"), after["how"]) and not R.flat(after.get("changed") or ""):
|
|
172
189
|
bad("runs", after["dir"], f"ran a plan/ that differs from {before['id']}'s and does not say what changed and why")
|
|
173
190
|
finished = [r for r in x["runs"] if r["state"] == "finished"]
|
|
174
191
|
if len(finished) > 1:
|
|
@@ -11,7 +11,9 @@ same place: what was committed under the old name is held under the new one.
|
|
|
11
11
|
|
|
12
12
|
- A committed `lock.json` is byte for byte its first committed version.
|
|
13
13
|
- `log.md`, `reviews.tsv` and `runs.tsv` only grow: no committed line is removed or changed.
|
|
14
|
-
- A `results.tsv` that a review has passed keeps every committed row.
|
|
14
|
+
- A `results.tsv` that a review has passed keeps every committed row. Once a results review that passed is committed
|
|
15
|
+
together with the rows it read, those rows stay, whatever the card and the file say later. Rows committed while
|
|
16
|
+
the last passed review was of other rows, such as a draft row added after it, were never reviewed and are not held.
|
|
15
17
|
- A settled decision keeps its `decided:`, its `about:` and its Decided text as first committed.
|
|
16
18
|
- A resource, once committed, is never removed. A metered resource's `granted`, `per_run` and `unit` change only together
|
|
17
19
|
with `from`, which then names another settled decision that lists the resource. Its `other_use` rows only grow.
|
|
@@ -179,6 +181,10 @@ def check(lab):
|
|
|
179
181
|
bad = lambda where, what: problems.append(f"history: {where}: {what}")
|
|
180
182
|
if not committed(root):
|
|
181
183
|
return [], ["this lab is not in git, or has no commit: permanence against history was not checked, and nothing recorded is held yet"]
|
|
184
|
+
notes = []
|
|
185
|
+
if (git(root, "rev-parse", "--is-shallow-repository") or "").strip() == "true":
|
|
186
|
+
notes.append("this repository is a shallow clone: the history check needs every commit, and compared the record with the few that are here. "
|
|
187
|
+
"Fetch the full history (`git fetch --unshallow`; in CI, `fetch-depth: 0`)")
|
|
182
188
|
versions, now = held(root, "log.md", "decisions", "goals"), present(root)
|
|
183
189
|
reviewed = {os.path.join(x["dir"], "results.tsv") for x in lab.experiments if x["reviewed"]}
|
|
184
190
|
for where, commits in sorted(versions.items()):
|
|
@@ -203,6 +209,34 @@ def check(lab):
|
|
|
203
209
|
bad(mine(path), f"a line committed in {c[:8]}{named(path)} is gone or changed: {lost[:70]!r}")
|
|
204
210
|
break
|
|
205
211
|
|
|
212
|
+
# A results review that passed, once committed with the rows it read, holds those rows: emptying the file with
|
|
213
|
+
# Found and Means leaves the experiment unreviewed now, and the rows are held all the same. The review is bound to
|
|
214
|
+
# what it read by its `of`, the hash `lab review` wrote: of results.tsv and of the seal of the finished run, both
|
|
215
|
+
# as that commit has them. Rows in a commit whose last passed review is of other rows were never reviewed.
|
|
216
|
+
for where, commits in sorted(versions.items()):
|
|
217
|
+
if os.path.basename(commits[-1][1]) != "reviews.tsv":
|
|
218
|
+
continue
|
|
219
|
+
rows, read = where.rsplit("/", 1)[0] + "/results.tsv", set()
|
|
220
|
+
if rows not in now:
|
|
221
|
+
continue # never committed, so nothing is held; or committed and gone, which is said above
|
|
222
|
+
for c, path in reversed(commits + versions.get(rows, [])): # every commit that touched the reviews or the rows
|
|
223
|
+
folder = os.path.dirname(path)
|
|
224
|
+
if c in read:
|
|
225
|
+
continue
|
|
226
|
+
read.add(c)
|
|
227
|
+
passed = [r for r in R.table(git(root, "show", f"{c}:./{folder}/reviews.tsv") or "", R.COLUMNS["reviews.tsv"]) if r.get("stage") == "results" and r.get("verdict") == "pass"]
|
|
228
|
+
was = git(root, "show", f"{c}:./{folder}/results.tsv") if passed else None
|
|
229
|
+
if was is None:
|
|
230
|
+
continue
|
|
231
|
+
listed = [l.split("\t") for l in (git(root, "show", f"{c}:./{folder}/runs.tsv") or "").split("\n")]
|
|
232
|
+
seals = [l[5] for l in listed if len(l) >= 6 and l[1] == "run" and l[2] == "ended" and l[4] == "0"] # the finished run, as that commit lists it
|
|
233
|
+
if passed[-1].get("of") not in {R.text_hash(R.text_hash(was) + str(seal))[:16] for seal in seals}:
|
|
234
|
+
continue # the last review that passed there read other rows than these
|
|
235
|
+
lost = subsequence(was.splitlines(), R.read(os.path.join(root, now[rows][0])).splitlines())
|
|
236
|
+
if lost is not None:
|
|
237
|
+
bad(now[rows][0], f"a row that a review had passed in {c[:8]} is gone or changed: {lost[:70]!r}. Reviewed rows stay; a different result is a new experiment")
|
|
238
|
+
break
|
|
239
|
+
|
|
206
240
|
problems += decisions(lab, versions, now)
|
|
207
241
|
problems += resources(lab)
|
|
208
|
-
return sorted(set(problems)),
|
|
242
|
+
return sorted(set(problems)), notes
|
|
@@ -17,8 +17,8 @@ KINDS = ["decision", "agent", "result", "stuck", "doing"] # a decision recorded
|
|
|
17
17
|
CLOSES = ("agent", "result", "stuck") # a later line of these kinds about the same card ends a `doing` line
|
|
18
18
|
SLOTS = { # every slot a card has, with its word budget
|
|
19
19
|
"goal": (("Claim", 90), ("Example", 260), ("Approach", 340), ("Roles", 170), ("Vocabulary", 260)),
|
|
20
|
-
"question": (("How we would know", 150), ("Example", 380), ("We expect", 70), ("Wrong if", 70), ("So far",
|
|
21
|
-
"experiment": (("Compares", 80), ("Arms", 260), ("Cases", 100), ("Confirmed if", 150), ("Refuted if", 110), ("Outcomes", 200), ("Limits", 120), ("Found",
|
|
20
|
+
"question": (("How we would know", 150), ("Example", 380), ("We expect", 70), ("Wrong if", 70), ("So far", 180)),
|
|
21
|
+
"experiment": (("Compares", 80), ("Arms", 260), ("Cases", 100), ("Confirmed if", 150), ("Refuted if", 110), ("Outcomes", 200), ("Limits", 120), ("Found", 180), ("Means", 150)),
|
|
22
22
|
"build": (("How it works", 200), ("Works when", 80)),
|
|
23
23
|
"reading": (("Looks at", 110), ("Seen", 320), ("Suggests", 150)),
|
|
24
24
|
"decision": (("Seen", 120), ("Options", 200), ("Recommendation", 80)),
|
|
@@ -143,6 +143,16 @@ def symlinks(folder):
|
|
|
143
143
|
return sorted(out)
|
|
144
144
|
|
|
145
145
|
|
|
146
|
+
def compiled(folder):
|
|
147
|
+
"""Every `.pyc` file under a folder that is not inside a `__pycache__`. Python imports such a file as it would the
|
|
148
|
+
script of the same name, and no hash of the folder covers it."""
|
|
149
|
+
out = []
|
|
150
|
+
for top, dirs, files in os.walk(folder):
|
|
151
|
+
dirs[:] = [d for d in dirs if d != "__pycache__"]
|
|
152
|
+
out += [os.path.relpath(os.path.join(top, n), folder) for n in files if n.endswith(".pyc")]
|
|
153
|
+
return sorted(out)
|
|
154
|
+
|
|
155
|
+
|
|
146
156
|
def sha(path):
|
|
147
157
|
return hashlib.sha256(open(path, "rb").read()).hexdigest()
|
|
148
158
|
|
|
@@ -151,17 +161,18 @@ def text_hash(text):
|
|
|
151
161
|
return hashlib.sha256(text.encode()).hexdigest()
|
|
152
162
|
|
|
153
163
|
|
|
154
|
-
def tree_hash(folder, how=HASH):
|
|
164
|
+
def tree_hash(folder, how=HASH, cache=False):
|
|
155
165
|
"""One hash over a folder: every file's path and bytes, each preceded by its length, so that no two folders give
|
|
156
166
|
the same hash. The first way (`how` 1: the path, a newline, the bytes) is kept to verify what was made with it.
|
|
157
167
|
What Python leaves when it imports a script is not part of the folder, in either way: a `__pycache__` folder with
|
|
158
|
-
everything under it, and a `*.pyc` file wherever it sits.
|
|
168
|
+
everything under it, and a `*.pyc` file wherever it sits. With `cache` those are hashed too, which is what
|
|
169
|
+
lab-kit 1.0.0 did: kept only to verify a plan that 1.0.0 locked or ran while such files sat in it."""
|
|
159
170
|
h, walked = hashlib.sha256(), []
|
|
160
171
|
for root, dirs, files in os.walk(folder):
|
|
161
|
-
dirs[:] = [d for d in dirs if d != "__pycache__"] # as the walk goes: sorting the walk first would read them all
|
|
172
|
+
dirs[:] = [d for d in dirs if cache or d != "__pycache__"] # as the walk goes: sorting the walk first would read them all
|
|
162
173
|
walked.append((root, files))
|
|
163
174
|
for root, files in sorted(walked):
|
|
164
|
-
for name in sorted(f for f in files if not f.endswith(".pyc")):
|
|
175
|
+
for name in sorted(f for f in files if cache or not f.endswith(".pyc")):
|
|
165
176
|
p = os.path.join(root, name)
|
|
166
177
|
path, data = os.path.relpath(p, folder).encode(), open(p, "rb").read()
|
|
167
178
|
h.update(path + b"\n" + data if how == 1 else len(path).to_bytes(8, "big") + path + len(data).to_bytes(8, "big") + data)
|
|
@@ -324,7 +335,8 @@ class Lab:
|
|
|
324
335
|
self.results[row["ref"]] = row
|
|
325
336
|
for q in self.questions:
|
|
326
337
|
q["state"] = self._question_state(q)
|
|
327
|
-
|
|
338
|
+
self.reach = self._reach()
|
|
339
|
+
for x in self._in_order(): # a step after everything it needs, wherever that sits in the tree
|
|
328
340
|
x["state"], x["next"], x["mine"] = {"build": self._build_state, "reading": self._reading_state, "experiment": self._experiment_state}[x["type"]](x)
|
|
329
341
|
for row in self.results.values(): # a number may be used on a card once its experiment is reviewed, and until it is replaced
|
|
330
342
|
x = self.nodes[row["experiment"]]
|
|
@@ -458,9 +470,20 @@ class Lab:
|
|
|
458
470
|
group = block[2:].strip()
|
|
459
471
|
elif block.startswith("## "):
|
|
460
472
|
head, _, rest = block[3:].partition("\n")
|
|
461
|
-
code = re.search(
|
|
473
|
+
code, avoid, see = (re.search(rf"^- {key}: (.+)$", rest, flags=re.M) for key in ("code", "avoid", "see"))
|
|
462
474
|
definition = " ".join(l for l in rest.split("\n") if l.strip() and not l.startswith("- ")).strip()
|
|
463
|
-
out.append({"term": head.strip(), "group": group, "definition": definition, "code": code.group(1).strip("` ") if code else ""
|
|
475
|
+
out.append({"term": head.strip(), "group": group, "definition": definition, "code": code.group(1).strip("` ") if code else "",
|
|
476
|
+
"avoid": [w for w in (w.strip("` ") for w in re.split(r"[,;]", avoid.group(1))) if w] if avoid else [], "see": see.group(1).strip("` ") if see else ""})
|
|
477
|
+
return out
|
|
478
|
+
|
|
479
|
+
def vocabulary(self, goal):
|
|
480
|
+
"""The names a goal's Vocabulary lists, each with its glossary entry (None when the glossary lacks it) and whether
|
|
481
|
+
it was written the old way, with a meaning after a colon. The meaning is never read: only the glossary defines."""
|
|
482
|
+
by = {g["term"].lower(): g for g in self.glossary}
|
|
483
|
+
out = []
|
|
484
|
+
for item in items(goal["slots"].get("Vocabulary", "")):
|
|
485
|
+
name, colon, _ = item.partition(":")
|
|
486
|
+
out.append({"name": name.strip(), "entry": by.get(name.strip().lower()), "old": bool(colon)})
|
|
464
487
|
return out
|
|
465
488
|
|
|
466
489
|
def _lines(self, text):
|
|
@@ -715,9 +738,22 @@ class Lab:
|
|
|
715
738
|
def before_hash(self, x):
|
|
716
739
|
return text_hash("\n".join(f"{k}\n{flat(x['slots'].get(k, ''))}" for k in BEFORE))
|
|
717
740
|
|
|
718
|
-
def plan_hash(self, x, how=HASH):
|
|
741
|
+
def plan_hash(self, x, how=HASH, cache=False):
|
|
719
742
|
d = os.path.join(self.root, x["dir"], "plan")
|
|
720
|
-
return tree_hash(d, how) if os.path.isdir(d) else "-"
|
|
743
|
+
return tree_hash(d, how, cache) if os.path.isdir(d) else "-"
|
|
744
|
+
|
|
745
|
+
def plan_is(self, x, pinned, how=HASH):
|
|
746
|
+
"""Whether a hash of plan/ that a lock or a run holds is plan/ as it is now. lab-kit 1.0.0 hashed what Python
|
|
747
|
+
leaves in a folder, and no later kit does: under a lock that 1.0.0 made, a hash that does not match is tried
|
|
748
|
+
once more the way 1.0.0 hashed, before a change is reported."""
|
|
749
|
+
if pinned == self.plan_hash(x, how):
|
|
750
|
+
return True
|
|
751
|
+
return (x.get("lock") or {}).get("kit") == "1.0.0" and pinned == self.plan_hash(x, how, cache=True)
|
|
752
|
+
|
|
753
|
+
def plans_differ(self, x, a, b, how=HASH):
|
|
754
|
+
"""Whether two hashes of plan/, held by a lock and a run or by two runs, are of two different plans. Under a
|
|
755
|
+
lock that 1.0.0 made, one may count what Python left and the other not: both are then plan/ as it is now."""
|
|
756
|
+
return a != b and not (self.plan_is(x, a, how) and self.plan_is(x, b, how))
|
|
721
757
|
|
|
722
758
|
def content(self, x, stage, how=HASH):
|
|
723
759
|
"""One hash of what a review of this stage reads: the lines and the plan, or the results and the run they come
|
|
@@ -776,6 +812,41 @@ class Lab:
|
|
|
776
812
|
return q["answer"]
|
|
777
813
|
return "open" if self.settled(q) else "under discussion"
|
|
778
814
|
|
|
815
|
+
def _reach(self):
|
|
816
|
+
"""For each step, every step it needs, directly or through what it needs: {id: {ids}}. A step that is in its
|
|
817
|
+
own set needs itself, which `lab check` reports."""
|
|
818
|
+
needs = {x["id"]: [i for i in x["needs"] if self.nodes.get(i, {}).get("type") in STEPS] for x in self.items}
|
|
819
|
+
out = {}
|
|
820
|
+
for ident in needs:
|
|
821
|
+
seen, todo = set(), list(needs[ident])
|
|
822
|
+
while todo:
|
|
823
|
+
i = todo.pop()
|
|
824
|
+
if i not in seen:
|
|
825
|
+
seen.add(i)
|
|
826
|
+
todo += needs[i]
|
|
827
|
+
out[ident] = seen
|
|
828
|
+
return out
|
|
829
|
+
|
|
830
|
+
def _in_order(self):
|
|
831
|
+
"""The steps in the order their states are worked out: each after every step it needs, earlier or later in the
|
|
832
|
+
tree, and otherwise in tree order. Steps that need each other in a circle have no such order: the walk does not
|
|
833
|
+
go round, and `_blocked` holds each of them whatever the others' states."""
|
|
834
|
+
by, out, met = {x["id"]: x for x in self.items}, [], set()
|
|
835
|
+
for first in self.items:
|
|
836
|
+
if first["id"] in met:
|
|
837
|
+
continue
|
|
838
|
+
met.add(first["id"])
|
|
839
|
+
path = [(first, iter(first["needs"]))]
|
|
840
|
+
while path:
|
|
841
|
+
x, needs = path[-1]
|
|
842
|
+
need = next((by[i] for i in needs if i in by and i not in met), None)
|
|
843
|
+
if need is None:
|
|
844
|
+
out.append(path.pop()[0])
|
|
845
|
+
else:
|
|
846
|
+
met.add(need["id"])
|
|
847
|
+
path.append((need, iter(need["needs"])))
|
|
848
|
+
return out
|
|
849
|
+
|
|
779
850
|
def _blocked(self, x):
|
|
780
851
|
"""Why nothing under this item may move yet, or None."""
|
|
781
852
|
q, g = self.nodes[x["question"]], self.nodes[x["goal"]]
|
|
@@ -787,7 +858,13 @@ class Lab:
|
|
|
787
858
|
return f"{q['id']} is {'answered ' + q['state'] if q['state'] in ('yes', 'no') else q['state']}"
|
|
788
859
|
for need in x.get("needs") or []:
|
|
789
860
|
n = self.nodes.get(need)
|
|
790
|
-
if n and
|
|
861
|
+
if n and x["id"] in self.reach.get(need, {need} if need == x["id"] else ()): # a circle of needs: nothing in it moves
|
|
862
|
+
return f"{need} {n['title']}, which needs {x['id']} in turn: no step in a circle of needs can move" if need != x["id"] else f"{need}, which is itself: a step cannot need itself"
|
|
863
|
+
if not n or n["type"] not in STEPS: # held here as `lab check` reports it: a need names a step
|
|
864
|
+
return f"{need}, which {'is not an experiment, a build or a reading' if n else 'does not exist'}: correct the need or remove it"
|
|
865
|
+
if n.get("state") in ("dropped", "replaced"): # it will never be done: waiting on it is waiting for ever
|
|
866
|
+
return f"{need} {n['title']}, which is {n['state']}: remove the need or replace it"
|
|
867
|
+
if n.get("state") not in ("done", "built"):
|
|
791
868
|
return f"{need} {n['title']}"
|
|
792
869
|
return None
|
|
793
870
|
|