lab-kit-cli 1.6.0__tar.gz → 1.8.0__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.
Files changed (43) hide show
  1. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/.github/workflows/policy.yml +5 -3
  2. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/AGENTS.md +7 -4
  3. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/CHANGELOG.md +29 -0
  4. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/PKG-INFO +2 -2
  5. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/README.md +1 -1
  6. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/docs/model.md +46 -10
  7. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/pyproject.toml +1 -1
  8. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/skills/lab-work/SKILL.md +9 -5
  9. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/__init__.py +1 -1
  10. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/checks.py +6 -2
  11. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/cli.py +1 -1
  12. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/record.py +45 -7
  13. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/site.py +101 -38
  14. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/write.py +7 -1
  15. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_parked.py +1 -0
  16. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_site.py +26 -2
  17. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_states.py +44 -0
  18. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/.github/workflows/ci.yml +0 -0
  19. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/.github/workflows/release.yml +0 -0
  20. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/.gitignore +0 -0
  21. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/CLAUDE.md +0 -0
  22. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/CONTRIBUTING.md +0 -0
  23. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/LICENSE +0 -0
  24. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/agents/reviewer.md +0 -0
  25. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/method/METHOD.md +0 -0
  26. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/skills/lab-mission/SKILL.md +0 -0
  27. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/skills/lab-review/SKILL.md +0 -0
  28. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/skills/lab-set-up/SKILL.md +0 -0
  29. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/skills/lab-talk/SKILL.md +0 -0
  30. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/history.py +0 -0
  31. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/runs.py +0 -0
  32. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/supervise.py +0 -0
  33. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/src/lab_kit/views.py +0 -0
  34. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_flow.py +0 -0
  35. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_held.py +0 -0
  36. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_integrity.py +0 -0
  37. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_mission.py +0 -0
  38. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_needs.py +0 -0
  39. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_order.py +0 -0
  40. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_refusals.py +0 -0
  41. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_vocabulary.py +0 -0
  42. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tests/test_wording.py +0 -0
  43. {lab_kit_cli-1.6.0 → lab_kit_cli-1.8.0}/tools/import_run.py +0 -0
@@ -1,10 +1,11 @@
1
1
  name: policy
2
2
 
3
- # Runs on pull requests only: a push straight to main is checked by the pre-push hook on the
4
- # machine that pushes (setup-machine), so GitHub spends no minutes on it (decision 0033).
3
+ # Runs on ready pull requests only: a push straight to main is checked by the pre-push hook on the
4
+ # machine that pushes (setup-machine), so GitHub spends no minutes on it (decision 0033). A draft
5
+ # cannot merge, so it is skipped, and marking it ready runs the check.
5
6
  on:
6
7
  pull_request:
7
- types: [opened, edited, synchronize, reopened]
8
+ types: [opened, edited, synchronize, reopened, ready_for_review]
8
9
 
9
10
  concurrency:
10
11
  group: policy-${{ github.event.pull_request.number }}
@@ -15,6 +16,7 @@ permissions:
15
16
 
16
17
  jobs:
17
18
  policy:
19
+ if: ${{ !github.event.pull_request.draft }}
18
20
  runs-on: ubuntu-latest
19
21
  steps:
20
22
  - uses: actions/checkout@v5
@@ -44,8 +44,11 @@ Every change goes through a pull request; `main` accepts nothing else.
44
44
 
45
45
  Run the gate before every push; CI also runs it on every pull request.
46
46
 
47
- **Authorship.** Every commit is authored with the repository owner's git identity. No co-author
48
- line, tool or agent name, "generated with" footer or session link appears in a commit message, a
49
- branch name or a pull request. The pre-push hook enforces it on every push, and a required `policy`
50
- check on every pull request.
47
+ **Authorship.** This repository is public. Every commit is authored with the repository owner's
48
+ git identity. No co-author line, tool or agent name, "generated with" footer or session link
49
+ appears in a commit message, a branch name or a pull request: name a branch after the task, never
50
+ `claude/…` or another tool's prefix. The pre-push hook (on every machine, and in cloud sessions
51
+ from their environment's setup script) enforces it on every push, ops' land-job `pr-check.sh`
52
+ checks a pull request's text before it is opened, and a required `policy` check runs on every ready
53
+ pull request.
51
54
  <!-- ops:lanes:end -->
@@ -1,5 +1,34 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.8.0
4
+
5
+ - **A question with nothing left under it is the agent's next step.** `lab now` ("Yours next") and Now's "Next for
6
+ the agent" list every open question that no open decision holds and that has no step open, waiting or running
7
+ under it: answer it, add the next experiment, or bring parking it to the operator. An open goal whose questions are
8
+ all answered, parked or dropped is listed too, to be closed in a decision, and so is an open goal with no question yet. Before, such a question was listed
9
+ nowhere, and stayed open in silence once its last experiment finished or a decision dropped its last step. The
10
+ skill `lab-work` changed: run `lab init` in a lab after upgrading.
11
+ - **An answer is written as itself, in a box:** yes, no, mixed or found, in the ink's colour, on Now and in the lists
12
+ of a lab's pages; the page header says "answered no" in the same box. Where only a sign fits, as in the rail and the
13
+ rows of marks, it is the word's first letter in a small box. It was a bare letter followed by "answered yes".
14
+ - **No key** on Now or in the rail: every mark names its state on hover.
15
+
16
+ ## 1.7.0
17
+
18
+ Two kinds of question, and the site draws every state with one mark, the same on every page.
19
+
20
+ - **A question is a test or an estimate** (`kind:` on its card; test is the default). A test asks whether something
21
+ holds and is answered yes, no or mixed. An estimate asks how much, which or what, and is answered `found`, with
22
+ the finding itself: `lab answer <question> found "<the finding, with its range, and what it rests on>"`. `lab
23
+ answer` and `lab check` refuse the other kind's answers. Its mark is F. The skill `lab-work` changed: run `lab
24
+ init` in a lab after upgrading.
25
+ - **One mark per state and label,** on Now, in the rail, in the page header, in the lists of steps, runs and reviews:
26
+ the shape carries the meaning and the colour follows it. Waiting is ‖, parked ◇, a decision to discuss ◆; a run or a
27
+ review that failed is ✗. Where a page writes a state out, it shows the mark and the word together, in its colour.
28
+ - **A goal or a question with a step running under it shows as running,** its mark pulsing, on Now and in the rail.
29
+ - **Now has the key** above the map of the lab, grouped by the kind of card; the rail's key is the same.
30
+ - A log line's kind is drawn without colour: colour is kept for states.
31
+
3
32
  ## 1.6.0
4
33
 
5
34
  One set of states for every card, and the checks that keep a card from saying what the record does not. The site's
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.6.0
3
+ Version: 1.8.0
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
@@ -33,7 +33,7 @@ record to the operator as a live site: `lab_kit.site` draws the pages, and nothi
33
33
 
34
34
  ```
35
35
  Goal what the lab wants to be able to say
36
- Question a question answered yes, no or mixed: what we expect, what would prove us wrong, what we know so far
36
+ Question a test (answered yes, no or mixed) or an estimate (answered with what was found): what we expect, what would prove us wrong, what we know so far
37
37
  Build something an experiment needs that has to be made first
38
38
  Reading a look at what already exists: it suggests, and never confirms
39
39
  Experiment what is compared, what would confirm, what would refute; then what was found
@@ -15,7 +15,7 @@ record to the operator as a live site: `lab_kit.site` draws the pages, and nothi
15
15
 
16
16
  ```
17
17
  Goal what the lab wants to be able to say
18
- Question a question answered yes, no or mixed: what we expect, what would prove us wrong, what we know so far
18
+ Question a test (answered yes, no or mixed) or an estimate (answered with what was found): what we expect, what would prove us wrong, what we know so far
19
19
  Build something an experiment needs that has to be made first
20
20
  Reading a look at what already exists: it suggests, and never confirms
21
21
  Experiment what is compared, what would confirm, what would refute; then what was found
@@ -10,7 +10,7 @@ A lab is a tree, and the decisions that shaped it.
10
10
  | Thing | What it says | States |
11
11
  | --- | --- | --- |
12
12
  | **Goal** | A short name, what the lab wants to be able to say, and the claim: what we would report if the questions come out as expected, and against whose work. | open, done, dropped |
13
- | **Question** | A short name, and a question under a goal, answered yes, no or mixed, written in full: why we ask it, how we would know, what we expect, what would prove us wrong, what we know so far. | open, waiting, parked, done (yes, no or mixed), dropped |
13
+ | **Question** | A short name, and a question under a goal, written in full: why we ask it, how we would know, what we expect, what would prove us wrong, what we know so far. A test is answered yes, no or mixed; an estimate is answered with what was found. | open, waiting, parked, done (yes, no, mixed or found), dropped |
14
14
  | **Experiment** | One thing tried to answer a question. What it is for. Before the run: what is compared, each arm by name with what it is, the cases it runs on, what would confirm, what would refute. After: what was found, what it means. | open, waiting, running, done (confirmed, refuted, unclear or void), replaced, dropped |
15
15
  | **Build** | One thing an experiment needs that has to be made first: what it is for, how it works in plain words, and how we know it works. | open, waiting, running, done, dropped |
16
16
  | **Reading** | One look at what already exists: sealed runs, traces, the benchmark's own definitions. What it looks at; then what was seen and what that suggests. It sets no bar in advance, so it can suggest and never confirm. | open, waiting, running, done, dropped |
@@ -31,10 +31,22 @@ seven words, and each type uses only those it can be in:
31
31
  | replaced | redone by a newer experiment | | | yes | | |
32
32
  | dropped | will not be done | yes | yes | yes | yes | yes |
33
33
 
34
- Two types carry a label on done. A question's is its answer: **yes**, **no** or **mixed**, the answer to
35
- the question as asked, with one sentence on what it rests on. Mixed says which part held and which did
36
- not, and usually leads to a narrower question. An answer is a finding, never good or bad: no is not a
37
- failure. A question has no "unclear": while the evidence cannot answer it, it is open. An experiment's
34
+ Two types carry a label on done. A question's is its answer, and what it can be depends on the
35
+ question's kind, set when it is written (`kind:`):
36
+
37
+ - **A test** (the default) asks whether something holds: "Does the error halve when the sample
38
+ quadruples?" Its answer is **yes**, **no** or **mixed**, read against its We expect and Wrong if, with
39
+ one sentence on what it rests on. Mixed says which part held and which did not, and usually leads to
40
+ a narrower question.
41
+ - **An estimate** asks how much, which or what: "How little feedback does a session need?", "What did
42
+ the solver's search depend on?" Its answer is **found**, with the finding itself in one or two
43
+ sentences: a number with its range, or a short description, and what it rests on. Its We expect says
44
+ roughly what size or shape is expected, and its Wrong if what would surprise. An estimate is never
45
+ squeezed into yes or no, which would throw away the size and how sure it is.
46
+
47
+ Either kind is answered only from done experiments that are not void; the bars that confirm or refute
48
+ stay on the experiments. An answer is a finding, never good or bad: no is not a failure. A question has
49
+ no "unclear": while the evidence cannot answer it, it is open. An experiment's
38
50
  label is its outcome: **confirmed**, **refuted** or **unclear**, read against the bars set before the
39
51
  run, or **void** when its results review failed, so that its numbers cannot be cited. A decision is open,
40
52
  then done; a mission's `status:` (next, current, done, stopped) reads on the pages as open, running,
@@ -277,6 +289,16 @@ never come back, with `dropped: <why>` on its card; park one that may.
277
289
  its reason, whether or not its card says so: the card needs no edit, and none can be forgotten. A goal is closed by `reached: true` or
278
290
  `dropped: <why>`, and a dropped goal drops every question under it.
279
291
 
292
+ **Nothing is left in silence.** An answer is never worked out from the experiments: everything under a
293
+ question being done can mean that it is answered or that the next experiment is due, and only someone reading
294
+ the question can tell. So `lab now` ("Yours next") and Now's "Next for the agent" list, after the steps the
295
+ agent can move, every open question that no open decision holds and that has no step open, waiting or running
296
+ under it, with what is next on it: to answer it, add the next experiment or bring parking it to you when an
297
+ experiment under it finished and is not void; to add an experiment, or bring parking or dropping it to you,
298
+ when none did; to plan its first experiment when nothing is under it yet. An open goal whose every question is
299
+ answered, parked or dropped is listed too: closing it is brought to you in a decision; and so is an open goal
300
+ with no question yet, whose first question is brought to you in a decision.
301
+
280
302
  **The order of the work.** What the agent takes up first is agreed with you, and a settled decision records
281
303
  it: `order:` lists goals, questions and steps, first to last. `lab now` ("Yours next", "Not yours to move yet")
282
304
  and the site's Now page list steps in that order. A step takes the place of its own id where the order names it,
@@ -297,8 +319,8 @@ change once committed; a change of mind is a new decision. `lab check` holds thi
297
319
  history. So a decision cannot be made, afterwards, to be about something it never discussed.
298
320
 
299
321
  The agent decides everything else and records each choice in the log. It drops an experiment or a
300
- build that will not be done, saying why. It answers a question itself, yes, no or mixed, with `lab answer`, and
301
- the command refuses while an experiment of that question is neither done, replaced nor dropped, and
322
+ build that will not be done, saying why. It answers a question itself with `lab answer`: a test yes, no or mixed, an estimate found. The command refuses the other kind's answers, and
323
+ it refuses while an experiment of that question is neither done, replaced nor dropped, and
302
324
  when no experiment of it is done: a reading alone answers nothing. `lab check` asks the same of every
303
325
  answered question, and that the log holds the line `lab answer` wrote. It never asks you to check
304
326
  its work, which is the review's job, and it never opens a decision for something that is its own to
@@ -470,6 +492,20 @@ place and marked, with its goal, its question and its siblings in view. A questi
470
492
  dropped steps fold into one line at its end; a goal's parked and dropped questions into one line at
471
493
  its end.
472
494
 
495
+ **One mark for each state, everywhere.** Every word a page uses for where something stands has one
496
+ mark, a shape in a colour, and it is the same on Now, in the rail, in the page header, in a list of
497
+ steps and in a list of runs: open ○, waiting ‖, running ● (it pulses), parked ◇, done ✓, replaced and
498
+ dropped –; a question answered yes, no, mixed or found shows its answer as the word itself in a box (where only a
499
+ sign fits, as in the rail, the word's first letter, Y, N, M or F), in the ink's colour, since an answer is a finding
500
+ and never good or bad; an experiment confirmed ✓, refuted ✗, unclear ?, void !; a decision to
501
+ discuss ◆ or decided ✓; a run running, finished ✓ or failed ✗, and a review passed ✓ or failed ✗. The
502
+ shape carries the meaning, so colour is never the only signal. Where a page writes a state out, it
503
+ writes the mark and the word, in the mark's colour; an answer is written as its boxed word alone, except in the
504
+ page header, which says "answered no" in a box. A goal or a question that is open or waiting with a
505
+ step running under it shows as running, its mark pulsing, with the running steps named on hover; its
506
+ state in the record does not change. A log line's kind (found, stuck, decided) is a kind of event, not
507
+ a state, and is drawn without colour. There is no key: every mark names its state on hover.
508
+
473
509
  **How a page of a card reads.** Every page of a goal, a question or a step reads in the same order:
474
510
 
475
511
  1. The title, and the lead: a step's or a goal's description, a question's `asks:` line.
@@ -506,8 +542,8 @@ and the answer in chat cannot differ. An experiment's page is the evidence behin
506
542
  what is live at this moment (each run going, the current mission with the last line of its log, what
507
543
  the agent says it is on), each with a pulsing mark, and when the record last moved; what needs you (the
508
544
  open decisions) and what is next for the agent, in the agreed order of the work; the map, one row per
509
- goal with how many of its questions are answered, and one tile per live question with its state, its
510
- answer and one mark per step in tree order; what each resource has used of its grant, as a bar; the
545
+ goal with its mark and how many of its questions are answered, and one tile per live question with its
546
+ mark and its state written out (its answer once answered) and one mark per step in tree order; what each resource has used of its grant, as a bar; the
511
547
  latest events. There is no graph page: the rail is the tree and Now is the map.
512
548
 
513
549
  **An example on every question.** A question's page carries one case, step by step, as a numbered
@@ -581,7 +617,7 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
581
617
  | Card | Front matter | Slots (word budget) |
582
618
  | --- | --- | --- |
583
619
  | `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) |
584
- | `question.md` | `title:` (a short name), `asks:` (the question in full), `from:`, `needs:`; `dropped: <why>`; `answer:` (yes, no or mixed) and `answered:` are written by `lab answer` | description: why we ask (150), How we would know (180), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (220) |
620
+ | `question.md` | `title:` (a short name), `asks:` (the question in full), `kind:` (test, the default, or estimate), `from:`, `needs:`; `dropped: <why>`; `answer:` (yes, no or mixed for a test, found for an estimate) and `answered:` are written by `lab answer` | description: why we ask (150), How we would know (180), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (220) |
585
621
  | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:` (something outside the lab; never a goal, question, step or decision of the lab, which go under `needs:` and are waited on by themselves), `dropped: <why>` | description (80), So far: optional, everything observed since the plan was written (300), Compares: the comparison, in a sentence or a numbered list of the whole work (300), Arms (260), Cases (120), Confirmed if (150), Refuted if (110), Outcomes (260), Limits (160), Found (180), Means (150) |
586
622
  | `reading.md` | `title:`, `needs:`, `waiting_on:`, `dropped: <why>` | description (70), Looks at: what, and where it is (120), Seen (360), Suggests (150) |
587
623
  | `build.md` | `title:`, `needs:`, `waiting_on:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.6.0"
8
+ version = "1.8.0"
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" }]
@@ -115,11 +115,14 @@ parked question, and never take it up because it looks open: it is listed under
115
115
  records what was decided.
116
116
 
117
117
  A goal or a question is made out of a decision: `lab new question <goal> "<short name>" --asks "<the
118
- question, in full>" --from <decision>`. Its description is the motivation: why we ask, and what
118
+ question, in full>" --from <decision>`. Say its kind in the card's front matter: a **test** asks
119
+ whether something holds and is answered yes, no or mixed (the default, `kind: test`); an **estimate**
120
+ asks how much, which or what and is answered with what was found (`kind: estimate`). Never bend an
121
+ estimate into a yes-or-no question. Its description is the motivation: why we ask, and what
119
122
  depends on the answer. **How we would know** is the idea of the test in plain words, before any
120
123
  experiment exists. **Example** is one case, step by step, as a numbered list saying who does what:
121
124
  a real episode once there is one, and until then the flow, said to be only that. Then **We expect**
122
- and **Wrong if**. Nothing under it is locked or run
125
+ and **Wrong if** (for an estimate: roughly what size or shape is expected, and what would surprise). Nothing under it is locked or run
123
126
  until that decision is settled; after that it needs no further yes.
124
127
 
125
128
  ## An experiment
@@ -236,9 +239,10 @@ repository, tests first. When it works, put `commits:` and `tests:` on the card
236
239
 
237
240
  ## When all experiments of a question are done
238
241
 
239
- Decide whether they answer it. `lab answer <question> yes|no|mixed "<what the answer rests on>"`, and
240
- bring **So far** up to date. Yes and no say whether what the question expected held; mixed says part
241
- held and part did not, and the sentence says which. An answer rests on a done experiment that is not
242
+ `lab now` lists such a question under **Yours next**, and a goal whose questions are all settled. Decide whether they answer it. For a test, `lab answer <question> yes|no|mixed "<what the answer rests
243
+ on>"`: yes and no say whether what the question expected held; mixed says part held and part did not,
244
+ and the sentence says which. For an estimate, `lab answer <question> found "<the finding, with its range
245
+ or its shape, and what it rests on>"`. Then bring **So far** up to date. An answer rests on a done experiment that is not
242
246
  void. If they do not answer it, add the next experiment. An answer usually changes
243
247
  what should come next: open a decision.
244
248
 
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.6.0"
2
+ __version__ = "1.8.0"
@@ -7,7 +7,7 @@ from . import history, record as R, runs as runs_, write
7
7
 
8
8
  KEYS = { # what a card's front matter may hold; a state is never among them
9
9
  "goal": {"title", "from", "reached", "dropped", "see"},
10
- "question": {"title", "asks", "from", "needs", "answer", "answered", "dropped", "see"},
10
+ "question": {"title", "asks", "kind", "from", "needs", "answer", "answered", "dropped", "see"},
11
11
  "experiment": {"title", "needs", "uses", "override", "replaces", "because", "cost", "waiting_on", "dropped", "see"},
12
12
  "build": {"title", "needs", "commits", "tests", "waiting_on", "dropped", "see"},
13
13
  "reading": {"title", "needs", "waiting_on", "dropped", "see"},
@@ -93,8 +93,12 @@ def run(lab, rederive=True):
93
93
  for need in q["needs"]:
94
94
  if nodes.get(need, {}).get("type") != "question":
95
95
  bad("links", q["path"], f"needs {need}, which is not a question")
96
+ if q.get("kind") is not None and q.get("kind") not in R.KINDS_OF_QUESTION:
97
+ bad("cards", q["path"], "`kind:` is test or estimate")
96
98
  if q.get("answer") is not None and q.get("answer") not in R.ANSWERS:
97
- bad("cards", q["path"], "`answer:` is yes, no or mixed, written by `lab answer`")
99
+ bad("cards", q["path"], "`answer:` is yes, no or mixed for a test, or found for an estimate, written by `lab answer`")
100
+ elif q.get("answer") is not None and R.question_kind(q) in R.KINDS_OF_QUESTION and q["answer"] not in R.KINDS_OF_QUESTION[R.question_kind(q)]:
101
+ bad("questions", q["path"], f"is {'an estimate' if R.question_kind(q) == 'estimate' else 'a test'} and is answered {q['answer']}: a test is answered yes, no or mixed, an estimate found")
98
102
  if q.get("answer") in R.ANSWERS: # what `lab answer` requires holds for an answer however it got on the card
99
103
  waiting = [x["id"] for x in q["items"] if x["state"] not in R.CLOSED]
100
104
  if waiting:
@@ -20,7 +20,7 @@ To write
20
20
  lab new experiment|build|reading <question> "<title>" [--replaces <experiment> --because "<why>"]
21
21
  lab log <id> doing "<what you are starting on>" "<why now>"
22
22
  lab log <id> agent|result|stuck "<what happened>" ["<so what>"]
23
- lab answer <question> yes|no|mixed "<what the answer rests on>"
23
+ lab answer <question> yes|no|mixed|found "<what the answer rests on>" (found: for an estimate, the finding)
24
24
  To carry out a decision
25
25
  lab mission [<mission>] [--all] the open missions (--all: the closed too), or one whole: its rules, its steps, its log
26
26
  lab mission new "<title>" --carries <decision> save a mission; it is next until launched
@@ -32,10 +32,11 @@ MISSION_BUDGET = {"description": 80, "Rules": 200}
32
32
  MISSION_STATES = ("next", "current", "done", "stopped") # a mission's `status:`; done and stopped are closed, and the file is kept
33
33
  STEPS = ("experiment", "build", "reading")
34
34
  # One set of states for every goal, question and step (the model, section 1). A type uses only those it can be in. On
35
- # done, a question carries its answer (yes, no or mixed) and an experiment its outcome (confirmed, refuted, unclear or
35
+ # done, a question carries its answer (yes, no or mixed for a test, found for an estimate) and an experiment its outcome (confirmed, refuted, unclear or
36
36
  # void) as its label.
37
37
  STATES = ("open", "waiting", "running", "parked", "done", "replaced", "dropped")
38
- ANSWERS = ("yes", "no", "mixed")
38
+ ANSWERS = ("yes", "no", "mixed", "found")
39
+ KINDS_OF_QUESTION = {"test": ("yes", "no", "mixed"), "estimate": ("found",)} # what each kind of question may be answered
39
40
  CLOSED = ("done", "replaced", "dropped") # a step in one of these will not move again # what sits under a question: a locked comparison, something made, a look at what already exists
40
41
  READS = ("", "percent", "points") # how a result's value reads on a page
41
42
  BEFORE = ("Compares", "Arms", "Cases", "Confirmed if", "Refuted if", "Outcomes", "Limits") # what an experiment says before it runs: its plan, which So far, Found and Means are not part of
@@ -55,7 +56,7 @@ HASH = 2 # how a folder is hashed in the locks and runs made now; one without t
55
56
  NUMBER = re.compile(r"[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?")
56
57
  LISTS = {"goal": ("see",), "question": ("needs", "see"), "experiment": ("needs", "uses", "see"), "build": ("needs", "commits", "tests", "see"),
57
58
  "reading": ("needs", "see"), "decision": ("about", "holds", "parks", "unparks", "drops", "order", "see")} # the front matter keys that hold a list
58
- TEXTS = ("title", "asks", "from", "replaces", "because", "cost", "waiting_on", "dropped", "answered") # and those that hold one value
59
+ TEXTS = ("title", "asks", "kind", "from", "replaces", "because", "cost", "waiting_on", "dropped", "answered") # and those that hold one value
59
60
 
60
61
 
61
62
  def complement(a, b):
@@ -196,6 +197,11 @@ def seal_of(record):
196
197
  return hashlib.sha256(json.dumps({k: v for k, v in record.items() if k != "seal"}, sort_keys=True).encode()).hexdigest()
197
198
 
198
199
 
200
+ def question_kind(q):
201
+ """A question's kind: a test, answered yes, no or mixed, unless its card says it is an estimate, answered found."""
202
+ return str(q.get("kind") or "test")
203
+
204
+
199
205
  def flat(text):
200
206
  return " ".join(str(text).split())
201
207
 
@@ -773,7 +779,7 @@ class Lab:
773
779
  place = {}
774
780
  for i, ident in enumerate(d["order"]):
775
781
  place.setdefault(ident, i)
776
- rank = lambda x: next((place[i] for i in (x["id"], x["question"], x["goal"]) if i in place), len(d["order"]))
782
+ rank = lambda x: next((place[i] for i in (x["id"], x.get("question"), x.get("goal")) if i in place), len(d["order"]))
777
783
  return sorted(steps, key=rank) # a stable sort: what shares a place keeps the order of the tree
778
784
 
779
785
  def set_aside(self):
@@ -1021,7 +1027,7 @@ class Lab:
1021
1027
  if q["state"] == "parked":
1022
1028
  return f"{q['id']} is parked by {self.parked_by(q['id'])['id']}: a decision that unparks it comes first"
1023
1029
  if q["state"] != "open":
1024
- return f"{q['id']} is {'answered ' + q['label'] if q['state'] == 'done' else q['state']}"
1030
+ return f"{q['id']} is {('answered ' + q['label']) if q['state'] == 'done' and q['label'] != 'found' else 'answered with what was found' if q['state'] == 'done' else q['state']}"
1025
1031
  for need in x.get("needs") or []:
1026
1032
  n = self.nodes.get(need)
1027
1033
  if n and x["id"] in self.reach.get(need, {need} if need == x["id"] else ()): # a circle of needs: nothing in it moves
@@ -1149,8 +1155,40 @@ class Lab:
1149
1155
  return sum(v for v in ((r.get("used") or {}).get(name, 0) for r in x["runs"] + x["trials"]) if amount(v))
1150
1156
 
1151
1157
  def yours(self):
1152
- """Every experiment and build the agent can move now, with what is next on each."""
1153
- return self.in_order([x for x in self.items if x["mine"]])
1158
+ """Everything the agent can move now, with what is next on each: the steps, then the questions and goals that
1159
+ have nothing left under them to move."""
1160
+ return self.in_order([x for x in self.items if x["mine"]] + self.to_settle())
1161
+
1162
+ def to_settle(self):
1163
+ """The open questions with no step open, waiting or running under them, and the open goals whose every question
1164
+ is settled or that have none yet, each with what is next on it. Only someone reading the question can tell whether what finished
1165
+ answers it, so nothing here is worked out into an answer: it is listed so that it is never left in silence.
1166
+ What an open decision holds waits on the decision and is not listed. The text goes on the node as its `next`,
1167
+ as a step's does; a Lab is read afresh for every command."""
1168
+ out = []
1169
+ for g in self.goals:
1170
+ if g["state"] != "open" or self.holding(g["id"]):
1171
+ continue
1172
+ for q in g["questions"]:
1173
+ if q["state"] != "open" or self.holding(q["id"]) or any(x["state"] not in CLOSED for x in q["items"]):
1174
+ continue
1175
+ usable = [x["id"] for x in q["items"] if x["type"] == "experiment" and x["state"] == "done" and x.get("outcome") != "void"]
1176
+ if usable:
1177
+ q["next"] = (f"every step under it is closed and {', '.join(usable)} finished: answer it (lab answer {q['id']} ...), "
1178
+ "add the next experiment, or bring parking it to the operator in a decision")
1179
+ elif q["items"]:
1180
+ q["next"] = ("no step is left under it and no experiment finished that is not void: add an experiment, "
1181
+ "or bring parking or dropping it to the operator in a decision")
1182
+ else:
1183
+ q["next"] = f"nothing under it yet: plan its first experiment (lab new experiment {q['id']} \"<title>\")"
1184
+ out.append(q)
1185
+ if not g["questions"]:
1186
+ g["next"] = "no question under it yet: bring its first question to the operator in a decision"
1187
+ out.append(g)
1188
+ elif all(q["state"] in ("done", "parked", "dropped") for q in g["questions"]):
1189
+ g["next"] = "every question under it is answered, parked or dropped: bring closing it (reached or dropped) to the operator in a decision"
1190
+ out.append(g)
1191
+ return out
1154
1192
 
1155
1193
  def since(self, day=None):
1156
1194
  """What happened since the last decision was recorded, or since a day."""
@@ -11,19 +11,23 @@ from . import record as L
11
11
 
12
12
  GENERIC = {"model", "field", "source", "group", "stop", "case", "score", "port", "step", "pass", "run", "result"}
13
13
  e = html.escape
14
- TONES = {"running": "info", "finished": "ok", "failed": "bad", "pass": "ok", "fail": "bad"} # a run's state and a review's verdict, as pills
15
14
  # How every state and label is drawn, on every page, on Now and in the rail: its tone (the colour) and its sign (the
16
15
  # shape), so that colour is never the only signal. On done the label decides, and an answer is a finding, never good or
17
16
  # bad: yes, no and mixed share one neutral tone.
18
- LOOK = {"open": ("plain", "\u25cb"), "waiting": ("warn", "\u2016"), "parked": ("plain", "\u2016"), "running": ("info", "\u25cf"),
17
+ LOOK = {"open": ("plain", "\u25cb"), "waiting": ("warn", "\u2016"), "parked": ("plain", "\u25c7"), "running": ("info", "\u25cf"),
19
18
  "done": ("ok", "\u2713"), "confirmed": ("ok", "\u2713"), "unclear": ("warn", "?"), "refuted": ("bad", "\u2717"), "void": ("bad", "!"),
20
- "yes": ("ink", "Y"), "no": ("ink", "N"), "mixed": ("ink", "M"), "replaced": ("gone", "\u2013"), "dropped": ("gone", "\u2013"),
21
- "to discuss": ("warn", "\u25cf"), "decided": ("ok", "\u2713")}
22
- ORDER = ("running", "waiting", "open", "done", "confirmed", "yes", "no", "mixed", "unclear", "refuted", "void", "parked", "replaced", "dropped") # how counts are listed
19
+ "yes": ("ink", "Y"), "no": ("ink", "N"), "mixed": ("ink", "M"), "found": ("ink", "F"), "replaced": ("gone", "\u2013"), "dropped": ("gone", "\u2013"),
20
+ "to discuss": ("warn", "\u25c6"), "decided": ("ok", "\u2713"),
21
+ "finished": ("ok", "\u2713"), "failed": ("bad", "\u2717"), "pass": ("ok", "\u2713"), "fail": ("bad", "\u2717")}
22
+ ORDER = ("running", "waiting", "open", "done", "confirmed", "yes", "no", "mixed", "found", "unclear", "refuted", "void", "parked", "replaced", "dropped") # how counts are listed
23
23
  MARK = {"goal": "G", "question": "Q", "experiment": "E", "build": "B", "reading": "R", "decision": "D"}
24
24
  MEANS = {"running": "running", "waiting": "waiting", "open": "open", "done": "done", "confirmed": "confirmed", "yes": "answered yes", "no": "answered no",
25
- "mixed": "answered mixed", "unclear": "unclear", "refuted": "refuted", "void": "void: its results review failed", "parked": "parked",
26
- "replaced": "replaced", "dropped": "dropped"}
25
+ "mixed": "answered mixed", "found": "found", "unclear": "unclear", "refuted": "refuted", "void": "void", "parked": "parked",
26
+ "replaced": "replaced", "dropped": "dropped", "to discuss": "to discuss", "decided": "decided",
27
+ "finished": "finished", "failed": "failed", "pass": "passed", "fail": "failed"}
28
+ HINT = {"running": "work under way; on a goal or a question, a step under it is running", "waiting": "held by a step it needs, a decision or something outside the lab",
29
+ "parked": "set aside by a decision", "void": "its results review failed: its numbers are never used", "replaced": "redone by a newer experiment",
30
+ "dropped": "will not be done", "to discuss": "open: waits for you", "found": "an estimate, answered with what was found", "failed": "a run that stopped with an error, or a review that did not pass"}
27
31
 
28
32
 
29
33
  def nice(day):
@@ -68,20 +72,36 @@ def ordinal(n):
68
72
  return {1: "first", 2: "second", 3: "third", 4: "fourth", 5: "fifth", 6: "sixth"}.get(n, f"{n}th")
69
73
 
70
74
 
75
+ def running_under(n):
76
+ """The steps running under a goal or a question, in tree order."""
77
+ if n.get("type") == "question":
78
+ return [x for x in n.get("items") or [] if x["state"] == "running"]
79
+ if n.get("type") == "goal":
80
+ return [x for q in n.get("questions") or [] for x in running_under(q)]
81
+ return []
82
+
83
+
71
84
  def key(n):
72
- """The word a node's look is read from: its label on done (an answer, an outcome), else its state."""
85
+ """The word a node's look is read from: its label on done (an answer, an outcome), else its state. A goal or a
86
+ question that is open or waiting with a step running under it reads as running, so that the work shows at every
87
+ level of the tree; its state in the record is unchanged."""
73
88
  if n.get("type") == "decision":
74
89
  return "decided" if n["state"] == "done" else "to discuss"
90
+ if n.get("state") in ("open", "waiting") and running_under(n):
91
+ return "running"
75
92
  return n["label"] if n.get("state") == "done" and n.get("label") else n["state"]
76
93
 
77
94
 
78
95
  def label(n):
79
- """A node's state as the operator reads it: on done, a question shows its answer and an experiment its outcome."""
80
- if n.get("type") == "decision":
81
- return "decided" if n["state"] == "done" else "open"
82
- if n["state"] == "done" and n.get("label"):
83
- return f"answered {n['label']}" if n["type"] == "question" else n["label"]
84
- return n["state"]
96
+ """A node's state as the operator reads it, in the words every page uses: on done, a question shows its answer and an
97
+ experiment its outcome."""
98
+ return MEANS.get(key(n), key(n))
99
+
100
+
101
+ def hint(n):
102
+ """What a mark says on hover: the word, and for a goal or a question shown as running, what runs under it."""
103
+ under = running_under(n) if n.get("type") in ("goal", "question") and key(n) == "running" else []
104
+ return label(n) + (": " + ", ".join(x["id"] for x in under) + " running" if under else "")
85
105
 
86
106
 
87
107
  def tone(n):
@@ -101,9 +121,49 @@ def pill(text, t="plain"):
101
121
  return f'<span class="pill t-{t}">{e(str(text))}</span>'
102
122
 
103
123
 
104
- def dot(n):
105
- """A node's state as a sign in its tone: the same shape and colour as in the rail. A running step's sign pulses."""
106
- return f'<span class="sg t-{tone(n)}{" live" if n.get("state") == "running" else ""}" title="{e(label(n))}">{sign(n)}</span>'
124
+ def mark(k, title=""):
125
+ """The mark of a state or a label: its sign in its tone, the same shape and colour on every page and in the rail.
126
+ Running pulses."""
127
+ t, g = LOOK.get(k, ("plain", "\u25cb"))
128
+ return f'<span class="sg t-{t}{" live" if k == "running" else ""}" title="{e(title or MEANS.get(k, k))}">{g}</span>'
129
+
130
+
131
+ def dot(n, title=""):
132
+ """A node's mark."""
133
+ return mark(key(n), title or hint(n))
134
+
135
+
136
+ def status(n):
137
+ """A node's mark and its word, in its tone: how a state is written out wherever a page names it."""
138
+ h = hint(n)
139
+ return word(key(n), h if h != label(n) else "")
140
+
141
+
142
+ def word(k, title=""):
143
+ """A state or a label written out: its mark and the word, in its tone. An answer is written as itself, in a box
144
+ (yes, no, mixed, found): the box is its mark, and the word is the finding."""
145
+ t = LOOK.get(k, ("plain", ""))[0]
146
+ if t == "ink":
147
+ return f'<span class="ans" title="{e(title or HINT.get(k, MEANS.get(k, k)))}">{e(k)}</span>'
148
+ return f'<span class="stw t-{t}" title="{e(title or HINT.get(k, MEANS.get(k, k)))}">{mark(k, title)}{e(MEANS.get(k, k))}</span>'
149
+
150
+
151
+ def header_css():
152
+ """folio's page header shows the view's status as a pill: draw it with the same mark and tone as everywhere else."""
153
+ soft = {"ok": "ok-soft", "warn": "warn-soft", "bad": "bad-soft", "info": "info-soft"}
154
+ # The rail's answers: the letter boxed, as in a row of marks on a lab page.
155
+ out = ['.f-vsign[data-t="ink"]{border:1px solid var(--ink-3);border-radius:3px;padding:0 .2em;min-width:0;font-size:.62rem;line-height:1.2}']
156
+ for k, (t, g) in LOOK.items():
157
+ fg = {"plain": "ink-3", "gone": "ink-3", "ink": "ink"}.get(t, t)
158
+ sel = f'.f-status[data-s="{MEANS.get(k, k)}"]'
159
+ if t == "ink": # an answer: the words alone, boxed, as on every lab page
160
+ out.append(f'{sel}{{background:none;color:var(--ink);border:1px solid var(--ink-3)}}{sel}::before{{display:none}}')
161
+ continue
162
+ out.append(f'{sel}{{background:var(--{soft.get(t, "sunk")});color:var(--{fg})}}'
163
+ f'{sel}::before{{content:"{g}";width:auto;height:auto;border-radius:0;background:none;opacity:1;font-weight:700}}')
164
+ if k == "running":
165
+ out.append(f"@media (prefers-reduced-motion:no-preference){{{sel}::before{{animation:lv-pulse 1.6s ease-in-out infinite}}}}")
166
+ return "".join(out)
107
167
 
108
168
 
109
169
  def libraries(lab):
@@ -325,7 +385,11 @@ CSS = """
325
385
  .lv .sg.t-ok{color:var(--ok)}.lv .sg.t-warn{color:var(--warn)}.lv .sg.t-bad{color:var(--bad)}.lv .sg.t-info{color:var(--info)}.lv .sg.t-ink{color:var(--ink)}.lv .sg.t-gone{color:var(--ink-3)}
326
386
  .lv .t-ink{background:var(--sunk);color:var(--ink)}
327
387
  .lv .t-gone{background:none;color:var(--ink-3);text-decoration:line-through}
388
+ .lv .sg.t-ink{min-width:0;padding:.1em .28em;border:1px solid var(--ink-3);border-radius:3px;font-size:.62em;line-height:1.1;vertical-align:.12em}
389
+ .lv .ans{display:inline-block;padding:0 .45rem;border:1px solid var(--ink-3);border-radius:4px;font:650 .74rem/1.45 var(--sans);color:var(--ink);background:var(--surface);white-space:nowrap}
328
390
  .lv .live{animation:lv-pulse 1.6s ease-in-out infinite}
391
+ .lv .stw{display:inline-flex;gap:.25rem;align-items:baseline;background:none;font:600 .78rem/1.4 var(--sans);white-space:nowrap}
392
+ .lv .stw.t-plain,.lv .stw.t-gone{color:var(--ink-3);text-decoration:none}.lv .stw.t-ink{color:var(--ink)}
329
393
  @keyframes lv-pulse{0%,100%{opacity:1}50%{opacity:.3}}
330
394
  @media (prefers-reduced-motion:reduce){.lv .live{animation:none}}
331
395
  .lv .dash-live{background:var(--surface);border:1px solid var(--rule);border-left:3px solid var(--info);border-radius:8px;padding:.7rem 1rem;margin:.2rem 0 1rem;font:400 .95rem/1.5 var(--sans)}
@@ -346,7 +410,7 @@ CSS = """
346
410
  .lv .tile:hover{border-color:var(--accent)}
347
411
  .lv .tile.t-done{background:var(--sunk)}
348
412
  .lv .tile .top{display:flex;gap:.4rem;align-items:baseline}
349
- .lv .tile .id{font:500 .74rem var(--mono);color:var(--ink-3)}
413
+ .lv .tile .id{font:500 .74rem var(--mono);color:var(--ink-3);white-space:nowrap}
350
414
  .lv .tile .ttl{font-weight:600;color:var(--ink)}
351
415
  .lv .tile .st{margin:.15rem 0 .3rem;font-size:.78rem;color:var(--ink-3)}
352
416
  .lv .tile .marks{display:flex;flex-wrap:wrap;gap:.15rem .3rem;font-size:.95rem}
@@ -645,11 +709,10 @@ def log_html(lab, T, lines, with_about=True):
645
709
  return '<p class="muted">Nothing yet.</p>'
646
710
  out = ['<ul class="log">']
647
711
  for l in reversed(lines):
648
- kind_tone = {"result": "ok", "stuck": "bad", "decision": "info", "agent": "plain", "doing": "plain"}.get(l["kind"], "plain")
649
712
  who = {"decision": "decided", "agent": "agent", "doing": "started"}.get(l["kind"], l["kind"])
650
713
  so = f'<span class="so">{T(l["so"])}</span>' if l["so"] else ""
651
714
  about = ref(lab, l["about"]) if with_about else ""
652
- out.append(f'<li><span class="d">{clock(l["at"])}</span><span>{pill(who, kind_tone)}</span><span>{about}</span><span>{T(l["what"])}{so}</span></li>')
715
+ out.append(f'<li><span class="d">{clock(l["at"])}</span><span>{pill(who)}</span><span>{about}</span><span>{T(l["what"])}{so}</span></li>')
653
716
  return "".join(out) + "</ul>"
654
717
 
655
718
 
@@ -814,7 +877,7 @@ def qcard(lab, T, q):
814
877
  body = asks + (block(T, q["slots"].get("So far", "")) if live else f'<p class="muted">{T(q["description"])}</p>')
815
878
  count = f"{done} of {len(live)} steps done" if live else ""
816
879
  return (f'<div class="qrow"><div><h3>{dot(q)} <a href="/{q["id"]}">{e(q["title"])}</a></h3>{body}</div>'
817
- f'<div class="side">{pill(label(q), tone(q))}<br>{count}</div></div>')
880
+ f'<div class="side">{status(q)}<br>{count}</div></div>')
818
881
 
819
882
 
820
883
  def live_box(lab, T):
@@ -823,15 +886,15 @@ def live_box(lab, T):
823
886
  for x in lab.experiments:
824
887
  for r in x["runs"] + x["trials"]:
825
888
  if r["state"] == "running" and not r["orphan"]:
826
- rows.append(f'<p><span class="who">running</span><span class="sg t-info live">\u25cf</span> {named(lab, x["id"])}, since {clock(r["started"])}'
889
+ rows.append(f'<p><span class="who">running</span>{mark("running")} {named(lab, x["id"])}, since {clock(r["started"])}'
827
890
  + (f' on {e(", ".join(x["uses"]))}' if x["uses"] else "") + ".</p>")
828
891
  for m in [m for m in lab.missions if m["state"] == "current"]:
829
892
  last = next((l for l in reversed(m["log"]) if l.get("what")), None)
830
- rows.append(f'<p><span class="who">mission</span><span class="sg t-info live">\u25cf</span> {e(m["id"])} {e(m["title"])}'
893
+ rows.append(f'<p><span class="who">mission</span>{mark("running")} {e(m["id"])} {e(m["title"])}'
831
894
  + (f' <span class="muted">last, {nice(last["day"])} {e(last["time"])}: {T(last["what"])}</span>' if last else "") + "</p>")
832
895
  d = lab.doing()
833
896
  if d:
834
- rows.append(f'<p><span class="who">the agent</span><span class="sg t-info live">\u25cf</span> on {named(lab, d["about"])}: {T(d["what"])} <span class="muted">Why now:</span> {T(d["so"])} <span class="muted">Since {clock(d["at"])}.</span></p>')
897
+ rows.append(f'<p><span class="who">the agent</span>{mark("running")} on {named(lab, d["about"])}: {T(d["what"])} <span class="muted">Why now:</span> {T(d["so"])} <span class="muted">Since {clock(d["at"])}.</span></p>')
835
898
  elif rows:
836
899
  rows.append('<p><span class="who">the agent</span><span class="muted">has not said it is on anything.</span></p>')
837
900
  if not rows:
@@ -872,11 +935,11 @@ def tile(lab, T, q):
872
935
  """A question on Now: its state and answer, and one sign per step in tree order; what was replaced or dropped is a count."""
873
936
  live = [x for x in q["items"] if x["state"] not in ("replaced", "dropped")]
874
937
  gone = len(q["items"]) - len(live)
875
- marks = "".join(f'<span class="sg t-{tone(x)}{" live" if x["state"] == "running" else ""}" title="{e(x["id"])} {e(x["title"])}: {e(label(x))}">{sign(x)}</span>' for x in live)
938
+ marks = "".join(dot(x, f'{x["id"]} {x["title"]}: {label(x)}') for x in live)
876
939
  marks += f'<span class="gone" title="replaced or dropped">\u2013{gone}</span>' if gone else ""
877
940
  marks = marks or '<span class="muted" style="font-size:.78rem">nothing under it yet</span>'
878
- return (f'<a class="tile t-{q["state"]}" href="/{q["id"]}" title="{e(q["asks"])}"><div class="top">{dot(q)}<span class="id">{e(q["id"].split(".")[-1])}</span>'
879
- f'<span class="ttl">{e(q["title"])}</span></div><div class="st">{e(label(q))}</div><div class="marks">{marks}</div></a>')
941
+ return (f'<a class="tile t-{q["state"]}" href="/{q["id"]}" title="{e(q["asks"])}"><div class="top"><span class="id">{e(q["id"].split(".")[-1])}</span>'
942
+ f'<span class="ttl">{e(q["title"])}</span></div><div class="st">{status(q)}</div><div class="marks">{marks}</div></a>')
880
943
 
881
944
 
882
945
  def lab_map(lab, T):
@@ -959,7 +1022,7 @@ def set_aside_html(lab, T):
959
1022
  f'<p>{named(lab, q["id"])}: {T(str(q.get("dropped") or lab.nodes[q["goal"]].get("dropped") or ""))}</p>' for q in aside["dropped"]) + "</details>")
960
1023
  if aside["goals"]:
961
1024
  out.append(f'<details class="old"><summary>Closed goals ({len(aside["goals"])})</summary>' + "".join(
962
- f'<p>{named(lab, g["id"])}: {e(label(g))}{". " + T(str(g["dropped"])) if g.get("dropped") else ""}</p>' for g in aside["goals"]) + "</details>")
1025
+ f'<p>{named(lab, g["id"])}: {status(g)}{". " + T(str(g["dropped"])) if g.get("dropped") else ""}</p>' for g in aside["goals"]) + "</details>")
963
1026
  return "".join(out)
964
1027
 
965
1028
 
@@ -1020,7 +1083,7 @@ def step_row(lab, T, x):
1020
1083
  tries = len(lab.chain(x)) + 1 if x["type"] == "experiment" else 1
1021
1084
  tag = f'<span class="tries">{ordinal(tries)} plan</span>' if tries > 1 else ""
1022
1085
  tag = f'<span class="kind">{x["type"]}</span>' + tag
1023
- return (f'<details class="row"><summary>{dot(x)}<b>{e(x["title"])}{tag}</b><span>{pill(label(x), tone(x))}</span><span>{item_line(lab, T, x) or T(x["description"])}</span></summary>'
1086
+ return (f'<details class="row"><summary>{dot(x)}<b>{e(x["title"])}{tag}</b><span>{status(x)}</span><span>{item_line(lab, T, x) or T(x["description"])}</span></summary>'
1024
1087
  f'<div class="in"><p class="desc">{T(x["description"])}</p>{slot_text(lab, T, x)}{earlier(lab, T, x) if x["type"] == "experiment" else ""}<a href="/{x["id"]}" style="font:.85rem var(--sans)">Open {x["id"]}</a></div></details>')
1025
1088
 
1026
1089
 
@@ -1034,12 +1097,15 @@ def question_page(lab, T, q):
1034
1097
  body = [f'<h1>{e(q["title"])}</h1>']
1035
1098
  if q.get("asks") and q["asks"] != q["title"]:
1036
1099
  body.append(f'<p class="lead">{T(q["asks"])}</p>')
1100
+ kind = ("An estimate: answered with what was found, a number with its range or a description." if L.question_kind(q) == "estimate"
1101
+ else "A test: answered yes, no or mixed, against what we expect and what would prove us wrong.")
1102
+ body.append(f'<p class="muted" style="font:.84rem var(--sans);margin-top:-.4rem">{kind}</p>')
1037
1103
  if q["state"] == "parked":
1038
1104
  d = lab.parked_by(q["id"])
1039
1105
  body.append(f'<div class="box"><b>Set aside</b> by {named(lab, d["id"])}: nothing under it moves until a decision brings it back. {T(L.flat(d["slots"].get("Decided", "")))}</div>')
1040
1106
  body.append(picture(lab, q))
1041
1107
  before = [lab.nodes[i] for i in q["needs"] if i in lab.nodes]
1042
- body.append(slots(slot("Where we are coming from", "".join(f'<p>{named(lab, n["id"])} ({e(label(n))}).</p>' for n in before), "full") if before else "",
1108
+ body.append(slots(slot("Where we are coming from", "".join(f'<p>{named(lab, n["id"])} {status(n)}</p>' for n in before), "full") if before else "",
1043
1109
  so_far(lab, T, q)))
1044
1110
  body.append("<h2>The question, as asked</h2>" + slots(
1045
1111
  boxed(T, "Why we ask", q["description"]),
@@ -1148,7 +1214,7 @@ def runs_html(lab, T, x):
1148
1214
  changed = f'<br><span class="lbl">Changed since {since}</span> {T(r["changed"])}' if r.get("changed") else ""
1149
1215
  if r["missing"] and not r["lost"]:
1150
1216
  how += ' <span class="muted">It is listed in the experiment\'s record of runs, and its folder is not in the store here.</span>'
1151
- rows.append(f'<li><b>{name}</b> <span class="muted">{clock(r["started"])} UTC' + (f' on {e(", ".join(x["uses"]))}' if x["uses"] else "") + f'</span><br>{pill(r["state"], TONES.get(r["state"], "plain"))} {how}{changed}{folder}</li>')
1217
+ rows.append(f'<li><b>{name}</b> <span class="muted">{clock(r["started"])} UTC' + (f' on {e(", ".join(x["uses"]))}' if x["uses"] else "") + f'</span><br>{word(r["state"])} {how}{changed}{folder}</li>')
1152
1218
  note = ('<p class="muted" style="font:.84rem var(--sans)">An experiment is run until one run finishes. Between runs the apparatus may be fixed, and each run says what changed; '
1153
1219
  "what the experiment demands stays as it was locked. The first run that finishes is the only source of its results. "
1154
1220
  "A run's folder is in the lab's store, outside git.</p>") if n > 1 else ""
@@ -1159,7 +1225,7 @@ def reviews_html(x):
1159
1225
  if not x["reviews"]:
1160
1226
  return ""
1161
1227
  return ('<h3>Reviews</h3><table class="t"><tr><th>Reviewed</th><th>What</th><th>Verdict</th><th>By</th><th>Note</th></tr>' + "".join(
1162
- f'<tr><td>{nice(r["date"])}</td><td>the {e(r["stage"])}</td><td>{pill(r["verdict"], TONES.get(r["verdict"], "plain"))}</td><td>{e(r["by"])}</td><td>{review_note(r["note"])}</td></tr>' for r in x["reviews"]) + "</table>")
1228
+ f'<tr><td>{nice(r["date"])}</td><td>the {e(r["stage"])}</td><td>{word(r["verdict"])}</td><td>{e(r["by"])}</td><td>{review_note(r["note"])}</td></tr>' for r in x["reviews"]) + "</table>")
1163
1229
 
1164
1230
 
1165
1231
  def experiment_page(lab, T, x):
@@ -1181,7 +1247,7 @@ def experiment_page(lab, T, x):
1181
1247
  body.append(picture(lab, x))
1182
1248
  if x["state"] == "done" and x["label"] != "void": # what was observed comes first, apart from the plan
1183
1249
  body.append(slots(boxed(T, "What it means", s.get("Means", ""), "full key", x["id"]), boxed(T, "What was found", s.get("Found", ""), "full key", x["id"])))
1184
- body.append(f'<p class="outcome-line">{pill(x["outcome"], tone(x))} {e(decided_by(lab, x))}</p>')
1250
+ body.append(f'<p class="outcome-line">{status(x)} {e(decided_by(lab, x))}</p>')
1185
1251
  body.append(slots(so_far(lab, T, x, x["id"])))
1186
1252
  body.append(("<h2>The plan, as locked</h2>" if x["lock"] else "<h2>The plan, not locked yet</h2>") + slots(
1187
1253
  boxed(T, "What it compares", s.get("Compares", ""), extra=arms_table(lab, T, x)),
@@ -1391,7 +1457,7 @@ class Provider:
1391
1457
  body = re.sub(r"<h1>.*?</h1>", "", page["body"], count=1, flags=re.S)
1392
1458
  panels = [(title, _links(f'<div class="lv panelbox">{block}</div>')) for title, block in re.findall(r"<h4>(.*?)</h4>(.*?)(?=<h4>|$)", page["panel"], flags=re.S)]
1393
1459
  return View(title=page["title"], main=_links(f'<div class="lv">{body}</div>'), description=L.flat(description),
1394
- genre=genre, status=status, head=f"<style>{CSS}</style>", panels=panels, path=path)
1460
+ genre=genre, status=status, head=f"<style>{CSS}{header_css()}</style>", panels=panels, path=path)
1395
1461
 
1396
1462
  def rail(self):
1397
1463
  """The lab as a tree: each goal, its questions, each question's steps. Each row has the mark of its kind, its short
@@ -1401,7 +1467,7 @@ class Provider:
1401
1467
 
1402
1468
  def row(n, short):
1403
1469
  return {"title": n["title"], "url": f"/lab/{n['id']}/", "id": short, "kind": n["type"], "status": label(n), **({"mark": MARK[n["type"]]} if n["type"] in L.STEPS else {}),
1404
- "tone": tone(n), "sign": sign(n), "pulse": n["state"] == "running", "gone": n["state"] in ("replaced", "dropped")}
1470
+ "tone": tone(n), "sign": sign(n), "pulse": key(n) == "running", "gone": n["state"] in ("replaced", "dropped")}
1405
1471
 
1406
1472
  def summary(steps):
1407
1473
  out = {} # done and confirmed share a sign: one count
@@ -1428,9 +1494,6 @@ class Provider:
1428
1494
  if aside:
1429
1495
  questions.append({"title": f"set aside ({len(aside)})", "key": f"{g['id']}:aside", "fold": True, "items": [row(q, q["id"].split(".")[-1]) for q in aside]})
1430
1496
  out.append({**row(g, g["id"]), "items": questions, "summary": summary(under)})
1431
- legend = [{"mark": MARK[k], "text": k} for k in L.STEPS]
1432
- legend += [{"sign": LOOK[k][1], "tone": LOOK[k][0], "status": MEANS[k], "text": MEANS[k]} for k in ORDER]
1433
- out.append({"title": "Key", "legend": legend})
1434
1497
  return out
1435
1498
 
1436
1499
  def search(self):
@@ -234,9 +234,15 @@ def answer(lab, target, verdict, text):
234
234
  """The agent's answer to a question, once its experiments are done."""
235
235
  n = lab.nodes.get(target)
236
236
  if verdict not in R.ANSWERS:
237
- stop("an answer is yes, no or mixed: mixed when part of what was expected held and part did not, saying which")
237
+ stop("an answer is yes, no or mixed for a test (mixed when part of what was expected held and part did not, saying which), or found for an estimate")
238
238
  if not n or n["type"] != "question":
239
239
  stop(f"no question {target}")
240
+ kind = R.question_kind(n)
241
+ if kind not in R.KINDS_OF_QUESTION:
242
+ stop(f"{target} has `kind: {kind}`: a question is a test or an estimate")
243
+ if verdict not in R.KINDS_OF_QUESTION.get(kind, ()):
244
+ stop(f"{target} is an estimate: it is answered `found`, with the finding itself" if kind == "estimate"
245
+ else f"{target} is a test: it is answered yes, no or mixed; an estimate (`kind: estimate` on its card) is answered found")
240
246
  if not R.flat(text):
241
247
  stop("an answer says what it rests on")
242
248
  if n["state"] != "open":
@@ -33,6 +33,7 @@ def test_a_parked_question_leaves_the_work_and_comes_back_only_by_a_decision(tmp
33
33
  lab(root, "decide", d2, "--with", "Ada", "The biased coin is parked: the fair coin answers what the lab needs first. It comes back if the law holds.")
34
34
  now = lab(root, "now")
35
35
  assert "Set aside" in now and f"G1.Q2 (parked by {d2})" in now and "A biased sampler" not in now.split("Set aside")[0]
36
+ assert "G1.Q2" not in now.split("Yours next")[1].split("Not yours")[0] # parked: never listed as one to settle
36
37
  assert f"Parked by {d2}" in lab(root, "show", "G1.Q2")
37
38
  refused = lab(root, "new", "reading", "G1.Q2", "What the biased runs said", ok=False)
38
39
  assert f"parked by {d2}" in refused and "unparks" in refused and not glob.glob(f"{root}/goals/G1-*/Q2-*/2-*")
@@ -124,7 +124,6 @@ def test_the_rail_the_search_and_the_stamp_follow_the_record(tmp_path):
124
124
  goal = next(r for r in rail if r.get("kind") == "goal")
125
125
  question = goal["items"][0]
126
126
  assert question["kind"] == "question" and question["items"][0]["url"] == "/lab/G1.Q1.1/" and question["items"][0]["status"] == "open" and question["tone"] == "plain"
127
- assert rail[-1]["title"] == "Key" and any(k.get("status") == "running" for k in rail[-1]["legend"])
128
127
  assert any(s["url"] == "/lab/G1.Q1.1/" and "factor of four" in s["description"] for s in site.search()) and any(s["url"] == "/lab/D1/" for s in site.search())
129
128
  before = site.stamp()
130
129
  lab(root, "log", "G1.Q1.1", "stuck", "The machine is down.")
@@ -337,7 +336,8 @@ def test_a_step_that_needs_a_later_one_reads_on_every_page_as_it_does_in_the_com
337
336
  ident, d, later_card = across(root) # a reading, a build and an experiment under Q1, each needing a done reading under Q2
338
337
  site = Provider(root)
339
338
  front_page = site.get("").main
340
- assert agents_next(front_page) == 3 and "wait:" not in front_page
339
+ assert agents_next(front_page) == 4 and "wait:" not in front_page # the three steps, and Q2, whose only step is done
340
+ assert "no step is left under it and no experiment finished" in front_page
341
341
  for step in ("G1.Q1.1", "G1.Q1.2", ident):
342
342
  assert "Next, for the agent:" in site.get(step).main and "Waiting on" not in site.get(step).main, step
343
343
  assert "Waiting on" not in site.get("G1.Q1").main and site.get("G1.Q1").main.count("Next: ") == 3
@@ -436,3 +436,27 @@ def test_a_table_with_no_rows_and_a_title_that_ends_in_a_mark_are_drawn(tmp_path
436
436
  assert "What we know so far" in page
437
437
  other = Provider(root).get("G1.Q1.3").main
438
438
  assert '<a class="page" href="/lab/G1.Q1/"' in other and ">Does the error halve when the sample quadruples?</a>" in other
439
+
440
+
441
+ def test_every_state_has_one_mark_on_every_page_and_an_answer_is_a_boxed_word(tmp_path):
442
+ from lab_kit import site as S
443
+ root, ident, d, command = locked(tmp_path)
444
+ lab(root, "run", ident, "--wait", "--", *command)
445
+ from test_integrity import done
446
+ done(root, ident, d)
447
+ lab(root, "answer", "G1.Q1", "no", "It halves at 400 flips, so the law does not need a correction.")
448
+ site = Provider(root)
449
+ question = next(r for r in site.rail() if r.get("kind") == "goal")["items"][0]
450
+ no = S.LOOK["no"]
451
+ assert (question["status"], question["tone"], question["sign"]) == ("answered no", no[0], no[1]) # the rail
452
+ now = site.get("").main
453
+ tile = now[now.index('class="tile'):]
454
+ assert '<span class="ans" title="answered no">no</span>' in tile and "answered no</span>" not in tile # the tile on Now: the answer, boxed
455
+ assert site.get("G1.Q1").status == "answered no" and 'data-s="answered no"' in S.header_css() # the page header draws the same mark
456
+ assert 'class="legend"' not in now and site.rail()[-1]["title"] != "Key" # no key: every mark names itself on hover
457
+ assert S.mark("no") == '<span class="sg t-ink" title="answered no">N</span>' and "::before{display:none}" in S.header_css() and '.f-vsign[data-t="ink"]{border' in S.header_css()
458
+ assert len({S.LOOK[k] for k in ("open", "waiting", "running", "parked", "done", "dropped", "to discuss")}) == 7 # no two states share a mark
459
+ busy = {"type": "question", "state": "open", "items": [{"id": "G1.Q1.2", "state": "running"}]}
460
+ assert S.key(busy) == "running" and "G1.Q1.2 running" in S.dot(busy) and " live" in S.dot(busy) # a question with a running step pulses
461
+ assert S.key({"type": "goal", "state": "open", "questions": [busy]}) == "running"
462
+ assert S.key({**busy, "state": "parked"}) == "parked"
@@ -116,3 +116,47 @@ def test_a_need_is_met_by_what_a_replaced_experiment_made(tmp_path):
116
116
  front(reading, needs="[G1.Q1.2]")
117
117
  front(never, dropped='"Not needed after all."') # dropped with no finished run: what needs it waits for ever
118
118
  assert "which is dropped: remove the need or replace it" in lab(root, "show", "G1.Q1.3")
119
+
120
+
121
+ def test_a_test_is_answered_yes_no_or_mixed_and_an_estimate_with_what_was_found(tmp_path):
122
+ root = str(tmp_path)
123
+ qdir = open_question(root)
124
+ ident, d, command = experiment(root, command=WRITES % "0.5")
125
+ lab(root, "lock", ident)
126
+ lab(root, "run", ident, "--wait", "--", *command)
127
+ done(root, ident, d)
128
+ assert "is a test: it is answered yes, no or mixed" in lab(root, "answer", "G1.Q1", "found", "The ratio is 0.5.", ok=False)
129
+ front(f"{qdir}/question.md", kind="estimate")
130
+ assert "is an estimate: it is answered `found`" in lab(root, "answer", "G1.Q1", "yes", "It halves.", ok=False)
131
+ lab(root, "answer", "G1.Q1", "found", "The error at 400 flips is 0.5 of the error at 100, on one seed.")
132
+ assert "G1.Q1 (done, found)" in lab(root, "show", "G1.Q1") and "the record is sound" in lab(root, "check", "--no-rederive")
133
+ front(f"{qdir}/question.md", kind="test")
134
+ assert "is a test and is answered found" in lab(root, "check", "--no-rederive", ok=False)
135
+ front(f"{qdir}/question.md", kind="guess")
136
+ assert "`kind:` is test or estimate" in lab(root, "check", "--no-rederive", ok=False)
137
+ front(f"{qdir}/question.md", kind="[estimate]")
138
+ assert "`kind:` holds one value, not a list" in lab(root, "check", "--no-rederive", ok=False) # reported, not a crash
139
+
140
+
141
+ def test_a_question_with_nothing_left_under_it_is_the_agents_next_step(tmp_path):
142
+ root = str(tmp_path)
143
+ open_question(root)
144
+ yours = lambda: lab(root, "now").split("Yours next")[1].split("Not yours")[0]
145
+ assert "G1.Q1" in yours() and "nothing under it yet: plan its first experiment" in yours()
146
+ ident, d, command = experiment(root, command=WRITES % "0.5")
147
+ assert "G1.Q1 " not in yours().replace(ident, "") # a step under it can move: the step is listed, not the question
148
+ lab(root, "lock", ident)
149
+ lab(root, "run", ident, "--wait", "--", *command)
150
+ results(d)
151
+ lab(root, "review", ident, "results", "fail", "The seed was fixed after a first look.")
152
+ assert "no experiment finished that is not void" in yours() # a void experiment answers nothing
153
+ again, d2, command2 = experiment(root, title="The same, with the seed fixed first", command=WRITES % "0.5")
154
+ lab(root, "lock", again)
155
+ lab(root, "run", again, "--wait", "--", *command2)
156
+ done(root, again, d2)
157
+ assert f"{again} finished: answer it (lab answer G1.Q1 ...)" in yours()
158
+ card, dn = park(root, "G1.Q1", "Whether to go on", "", key="holds")
159
+ assert "G1.Q1" not in yours() and "G1 " not in yours() # what an open decision holds waits on it, and its goal is not settled either
160
+ lab(root, "decide", dn, "--with", "Ada", "Go on.")
161
+ lab(root, "answer", "G1.Q1", "yes", "It halves at 400 flips.")
162
+ assert "G1 " in yours() and "bring closing it (reached or dropped) to the operator" in yours()
File without changes
File without changes
File without changes
File without changes