lab-kit-cli 1.0.2__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.2 → lab_kit_cli-1.0.3}/CHANGELOG.md +20 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/PKG-INFO +1 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/docs/model.md +34 -3
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/pyproject.toml +1 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/skills/lab-set-up/SKILL.md +4 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/skills/lab-work/SKILL.md +7 -3
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/__init__.py +1 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/checks.py +27 -13
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/record.py +13 -2
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/site.py +21 -3
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/views.py +10 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_site.py +4 -3
- lab_kit_cli-1.0.3/tests/test_vocabulary.py +116 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/.github/workflows/ci.yml +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/.github/workflows/policy.yml +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/.github/workflows/release.yml +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/.gitignore +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/AGENTS.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/CLAUDE.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/CONTRIBUTING.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/LICENSE +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/README.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/agents/reviewer.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/method/METHOD.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/skills/lab-review/SKILL.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/skills/lab-talk/SKILL.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/cli.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/history.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/runs.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/supervise.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/write.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_flow.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_held.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_integrity.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_needs.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_refusals.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tools/import_run.py +0 -0
|
@@ -1,5 +1,25 @@
|
|
|
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
|
+
|
|
3
23
|
## 1.0.2
|
|
4
24
|
|
|
5
25
|
One defect found while rehearsing a real lab, four follow-ups from 1.0.1, and three larger word
|
|
@@ -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
|
|
@@ -325,7 +325,7 @@ Seven rules:
|
|
|
325
325
|
Never record a decision that was not discussed with them.
|
|
326
326
|
7. Say what you are on. When you start on a card, log what you are doing and why now.
|
|
327
327
|
|
|
328
|
-
`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
|
|
329
329
|
card, short cards that write only their own front matter, a test on every line, a reason on every
|
|
330
330
|
replacement, unchanged locks, sealed runs, results that still re-derive and were reviewed, use inside
|
|
331
331
|
the resources' amounts, a decision behind every goal, question and metered amount, an experiment
|
|
@@ -387,7 +387,8 @@ resource. Nothing on it is static text except one line per goal.
|
|
|
387
387
|
**An example on every question.** A question's page carries one case, step by step, as a numbered
|
|
388
388
|
list that says who does what: the user, the agent, the tools, the gate, the scorer. A real episode
|
|
389
389
|
where one exists, and said to be only the flow where none does. The goal's page says once who plays
|
|
390
|
-
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.
|
|
391
392
|
|
|
392
393
|
**What was dropped** stays in the record: a dropped goal or question keeps its card and its page,
|
|
393
394
|
and leaves Now, the rail and the graph.
|
|
@@ -449,7 +450,7 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
|
|
|
449
450
|
|
|
450
451
|
| Card | Front matter | Slots (word budget) |
|
|
451
452
|
| --- | --- | --- |
|
|
452
|
-
| `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, `- <
|
|
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) |
|
|
453
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) |
|
|
454
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) |
|
|
455
456
|
| `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
|
|
@@ -468,6 +469,36 @@ as in CI, which checks out the lab alone, the page cannot be looked for: that is
|
|
|
468
469
|
failure only with `--strict`. When the folder is there and the page is not, or the charter names no
|
|
469
470
|
such library, it is a problem.
|
|
470
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
|
+
|
|
471
502
|
**An arm** is a list item under Arms: its name, a colon, and what it is, so that a reader who has
|
|
472
503
|
never seen it knows what was run.
|
|
473
504
|
|
|
@@ -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,8 +36,12 @@ 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.
|
|
@@ -208,7 +212,7 @@ what should come next: open a decision.
|
|
|
208
212
|
- Never write that the operator decided something outside a decision recorded with `lab decide` (the
|
|
209
213
|
lab-talk skill).
|
|
210
214
|
- Open `plan/` and `runs/` only for the experiment you are working on.
|
|
211
|
-
- 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.
|
|
212
216
|
|
|
213
217
|
## Before you stop
|
|
214
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:
|
|
@@ -470,9 +470,20 @@ class Lab:
|
|
|
470
470
|
group = block[2:].strip()
|
|
471
471
|
elif block.startswith("## "):
|
|
472
472
|
head, _, rest = block[3:].partition("\n")
|
|
473
|
-
code = re.search(
|
|
473
|
+
code, avoid, see = (re.search(rf"^- {key}: (.+)$", rest, flags=re.M) for key in ("code", "avoid", "see"))
|
|
474
474
|
definition = " ".join(l for l in rest.split("\n") if l.strip() and not l.startswith("- ")).strip()
|
|
475
|
-
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)})
|
|
476
487
|
return out
|
|
477
488
|
|
|
478
489
|
def _lines(self, text):
|
|
@@ -190,6 +190,7 @@ CSS = """
|
|
|
190
190
|
.lv h3{margin:1.2em 0 .3em}
|
|
191
191
|
.lv .crumbs{font:500 .8rem var(--sans);color:var(--ink-3)}
|
|
192
192
|
.lv .crumbs a{color:var(--ink-3)}
|
|
193
|
+
.lv .avoid{display:block;font:.78rem var(--sans);color:var(--ink-3)}
|
|
193
194
|
.lv .lead{font-size:1.1rem;color:var(--ink-2);max-width:48rem}
|
|
194
195
|
.lv .pill{display:inline-block;padding:.08rem .55rem;border-radius:999px;font:600 .72rem/1.5 var(--sans);white-space:nowrap;background:var(--sunk);color:var(--ink-2)}
|
|
195
196
|
.lv .t-ok{background:var(--ok-soft);color:var(--ok)}
|
|
@@ -683,8 +684,10 @@ def goal_page(lab, T, g):
|
|
|
683
684
|
body.append('<div class="slots">' + "".join(slot(*x) for x in extra) + "</div>")
|
|
684
685
|
if pairs("Roles"):
|
|
685
686
|
body.append('<h2>Who plays what</h2><table class="t roles"><tr><th>Role</th><th>Played by, and what it does</th></tr>' + "".join(f"<tr><td>{T(a)}</td><td>{T(b)}</td></tr>" for a, b in pairs("Roles")) + "</table>")
|
|
686
|
-
|
|
687
|
-
|
|
687
|
+
words = lab.vocabulary(g)
|
|
688
|
+
if words: # the names are the card's; what each means is the glossary's, whatever the card says after a colon
|
|
689
|
+
rows = "".join(f'<tr><td>{e(w["entry"]["term"] if w["entry"] else w["name"])}</td><td>' + (e(w["entry"]["definition"]) + avoid_note(w["entry"]) if w["entry"] else '<span class="muted">not in the glossary</span>') + "</td></tr>" for w in words)
|
|
690
|
+
body.append('<h2>The words this lab uses</h2><table class="t roles"><tr><th>Word</th><th>What it means here, everywhere</th></tr>' + rows + "</table>")
|
|
688
691
|
body.append("<h2>Questions</h2>" + "".join(qcard(lab, T, q) for q in lab.live(g["questions"])))
|
|
689
692
|
gone = [q for q in g["questions"] if q["state"] == "dropped"]
|
|
690
693
|
if gone:
|
|
@@ -954,6 +957,20 @@ def resources_page(lab, T):
|
|
|
954
957
|
return frame(lab, "Resources", "".join(body))
|
|
955
958
|
|
|
956
959
|
|
|
960
|
+
def avoid_note(g):
|
|
961
|
+
"""The words not to use for a term, in small type; nothing when there are none."""
|
|
962
|
+
return f' <span class="avoid">Avoid: {e(", ".join(g["avoid"]))}</span>' if g["avoid"] else ""
|
|
963
|
+
|
|
964
|
+
|
|
965
|
+
def see_link(lab, page):
|
|
966
|
+
"""A link to the page that explains a term, a page of the lab's own library or of a library the charter names."""
|
|
967
|
+
page = str(page)
|
|
968
|
+
if ":" not in page:
|
|
969
|
+
return f'<a href="/docs/{e(page)}/">{e(pages(lab).get(page, page))}</a>'
|
|
970
|
+
url = outside(lab, page)
|
|
971
|
+
return f'<a href="{e(url)}">{e(page_title(lab, page))}</a>' if url else e(page)
|
|
972
|
+
|
|
973
|
+
|
|
957
974
|
def glossary_page(lab, T):
|
|
958
975
|
"""Every term, by group, each group closed until it is opened or the filter finds something in it."""
|
|
959
976
|
url = code_url(lab)
|
|
@@ -973,7 +990,8 @@ def glossary_page(lab, T):
|
|
|
973
990
|
rows = []
|
|
974
991
|
for g in terms:
|
|
975
992
|
code = (f' · <a href="{url}/blob/main/src/{e(g["code"].split(":")[0].replace(".", "/"))}.py"><code>{e(g["code"])}</code></a>' if url else f' · <code>{e(g["code"])}</code>') if g["code"] else ""
|
|
976
|
-
|
|
993
|
+
more = f' · See: {see_link(lab, g["see"])}' if g["see"] else ""
|
|
994
|
+
rows.append(f'<dt id="{e(g["term"].lower().replace(" ", "-"))}">{e(g["term"])}</dt><dd>{e(g["definition"])}{code}{more}{avoid_note(g)}</dd>')
|
|
977
995
|
body.append(f'<details class="ggroup"><summary>{e(name)}<span>{len(terms)} terms</span></summary><dl class="gloss">{"".join(rows)}</dl></details>')
|
|
978
996
|
body.append("<script>(function(){var h=decodeURIComponent(location.hash.slice(1));var t=h&&document.getElementById(h);if(t){t.closest('details').open=true;t.scrollIntoView();}})();</script>")
|
|
979
997
|
return frame(lab, "Glossary", "".join(body))
|
|
@@ -125,6 +125,9 @@ def _show(lab, ident):
|
|
|
125
125
|
if n["type"] == "goal":
|
|
126
126
|
out = [f"{n['id']} ({n['state']}): {n['title']}", n["description"]] + came(n) + ["", f"Claim. {R.flat(n['slots'].get('Claim', '')) or 'not written yet'}", "", "Questions"]
|
|
127
127
|
out += [f"- {q['id']} ({q['state']}): {q['title']}. {q['description']}" for q in n["questions"]]
|
|
128
|
+
words = lab.vocabulary(n)
|
|
129
|
+
if words: # the names are the card's; each is drawn with the glossary's definition
|
|
130
|
+
out += ["", "Vocabulary (defined in GLOSSARY.md)"] + [entry_text(w["entry"], "- ") if w["entry"] else f"- {w['name']}: not in the glossary" for w in words]
|
|
128
131
|
return "\n".join(out + ["", "More: lab show <question id>"])
|
|
129
132
|
about = [l for l in lab.lines if l["about"] == ident or l["about"].startswith(ident + ".")]
|
|
130
133
|
decisions = ["", "Decisions about it"] + [f"- {d['id']} ({d['state']}): {d['title']}" for d in raised] if raised else []
|
|
@@ -233,7 +236,13 @@ def define(lab, term):
|
|
|
233
236
|
hits = [g for g in lab.glossary if g["term"].lower() == term.lower()] or [g for g in lab.glossary if term.lower() in g["term"].lower()]
|
|
234
237
|
if not hits:
|
|
235
238
|
raise SystemExit(f"{term!r} is not in the glossary")
|
|
236
|
-
return "\n\n".join(
|
|
239
|
+
return "\n\n".join(entry_text(g) for g in hits)
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def entry_text(g, lead=""):
|
|
243
|
+
"""A glossary entry as the agent reads it: the definition, then the code, the words to avoid and the page that explains it."""
|
|
244
|
+
return (f"{lead}{g['term']}: {g['definition']}" + (f"\n code: {g['code']}" if g["code"] else "") + (f"\n avoid: {', '.join(g['avoid'])}" if g["avoid"] else "")
|
|
245
|
+
+ (f"\n see: {g['see']}" if g["see"] else ""))
|
|
237
246
|
|
|
238
247
|
|
|
239
248
|
def now(lab):
|
|
@@ -177,7 +177,8 @@ def test_a_readings_page_says_it_is_exploratory_and_what_was_dropped_leaves_the_
|
|
|
177
177
|
describe(card, "Reads the estimates that fell outside the band.")
|
|
178
178
|
fill(card, Looks_at="Twelve estimates.", Seen="1. Nine used the short sample.\n2. Three had the seed reset.", Suggests="Fix the seed.")
|
|
179
179
|
goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
|
|
180
|
-
fill(goal, Roles="- The sampler: our code. It draws every estimate.", Vocabulary="-
|
|
180
|
+
fill(goal, Roles="- The sampler: our code. It draws every estimate.", Vocabulary="- tally: the card's own meaning, which is never shown", Approach="**The design.** Flip, count, compare.")
|
|
181
|
+
open(f"{root}/GLOSSARY.md", "w").write("# Terms\n\n## tally\nOne share of heads, from one sample.\n")
|
|
181
182
|
question = glob.glob(f"{root}/goals/G1-*/Q1-*/question.md")[0]
|
|
182
183
|
fill(question, Example="1. **The sampler** flips a coin 100 times.\n2. **The scorer** compares the share of heads with one half.")
|
|
183
184
|
lab(root, "new", "question", "G1", "A side question", "--from", "D1")
|
|
@@ -187,7 +188,7 @@ def test_a_readings_page_says_it_is_exploratory_and_what_was_dropped_leaves_the_
|
|
|
187
188
|
assert page.status == "done" and "This looked at data the lab already had." in page.main and "<ol><li>Nine used the short sample.</li>" in page.main and "What it suggests" in page.main
|
|
188
189
|
q = site.get("G1.Q1").main
|
|
189
190
|
assert '<span class="kind">reading</span>' in q and "<ol><li><b>The sampler</b> flips a coin 100 times.</li>" in q and "Fix the seed." in q
|
|
190
|
-
assert "The words this lab uses" in site.get("G1").main and "
|
|
191
|
+
assert "The words this lab uses" in site.get("G1").main and "One share of heads, from one sample." in site.get("G1").main and "never shown" not in site.get("G1").main and "<b>The design.</b> Flip, count, compare." in site.get("G1").main
|
|
191
192
|
assert "Who plays what" in site.get("G1").main and "It draws every estimate." in site.get("G1").main and "Dropped questions (1)" in site.get("G1").main
|
|
192
193
|
assert "A side question" not in site.get("").main and not any("A side question" in str(r) for r in site.rail()) and site.get("G1.Q2") is not None
|
|
193
194
|
|
|
@@ -249,7 +250,7 @@ def test_nothing_written_in_a_lab_reaches_a_page_as_markup(tmp_path):
|
|
|
249
250
|
Q = json.dumps(P)
|
|
250
251
|
root = a_lab(tmp_path)
|
|
251
252
|
open(f"{root}/lab.toml", "a").write(f"code_url = {json.dumps('https://example.com/' + P)}\n")
|
|
252
|
-
open(f"{root}/GLOSSARY.md", "w").write(f"# {P}\n\n## sampler{P}\nWhat draws the estimates. {P}\n- code: {P}\n\n## estimate\nOne number from the sampler. {P}\n- code: sampler:{P}\n")
|
|
253
|
+
open(f"{root}/GLOSSARY.md", "w").write(f"# {P}\n\n## sampler{P}\nWhat draws the estimates. {P}\n- code: {P}\n\n## estimate\nOne number from the sampler. {P}\n- code: sampler:{P}\n- avoid: {P}, <b>x</b>\n- see: {P}\n")
|
|
253
254
|
open(f"{root}/resources.toml", "a").write(f"other_use = [{{date = \"2026-01-01\", amount = 1, what = {Q}}}]\n\n[{Q}]\nwhat = {Q}\nkey = {Q}\nunit = {Q}\ngranted = 5\nfrom = \"D1\"\nrules = [{Q}]\n")
|
|
254
255
|
goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
|
|
255
256
|
qdir = glob.glob(f"{root}/goals/G1-*/Q1-*")[0]
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
"""A word is defined once, in GLOSSARY.md: avoid and see on an entry, and a goal that lists names only."""
|
|
2
|
+
import glob, os
|
|
3
|
+
import re
|
|
4
|
+
|
|
5
|
+
import pytest
|
|
6
|
+
|
|
7
|
+
from test_flow import fill, front, lab, open_question
|
|
8
|
+
from test_integrity import commit, under
|
|
9
|
+
|
|
10
|
+
ENTRIES = ("# Words\n\n## guard\nThe part that reads every call and refuses the ones the contract forbids.\n- code: kna.gate:Guard\n- avoid: gate, filter, `policy`\n- see: entries/the-guard\n\n"
|
|
11
|
+
"## field\nOne number on a grid.\n\n## LoRA\nA small adapter trained beside a frozen model.\n- see: notes:/content/concepts/lora/\n")
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def a_lab(tmp_path, glossary=ENTRIES, vocabulary="- guard\n- field"):
|
|
15
|
+
root = under(tmp_path, "lab")
|
|
16
|
+
qdir = open_question(root)
|
|
17
|
+
open(f"{root}/GLOSSARY.md", "w").write(glossary)
|
|
18
|
+
goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
|
|
19
|
+
fill(goal, Vocabulary=vocabulary)
|
|
20
|
+
os.makedirs(f"{root}/docs/content/entries/the-guard")
|
|
21
|
+
open(f"{root}/docs/content/entries/the-guard/index.html", "w").write("<p>the guard</p>\n")
|
|
22
|
+
os.makedirs(tmp_path / "notes" / "content" / "concepts" / "lora")
|
|
23
|
+
open(tmp_path / "notes" / "content" / "concepts" / "lora" / "index.html", "w").write("<p>lora</p>\n")
|
|
24
|
+
open(f"{root}/docs/folio.yaml", "w").write("title: lab\nlibraries:\n notes:\n path: ../../notes\n url: https://notes.example\n")
|
|
25
|
+
commit(root)
|
|
26
|
+
return root, goal
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def test_avoid_and_see_are_read_and_shown_and_a_sound_lab_checks(tmp_path):
|
|
30
|
+
root, _ = a_lab(tmp_path)
|
|
31
|
+
out = lab(root, "define", "guard")
|
|
32
|
+
assert "guard: The part that reads every call" in out and "code: kna.gate:Guard" in out and "avoid: gate, filter, policy" in out and "see: entries/the-guard" in out
|
|
33
|
+
assert "avoid:" not in lab(root, "define", "field") and "see: notes:/content/concepts/lora/" in lab(root, "define", "LoRA")
|
|
34
|
+
assert "the record is sound" in lab(root, "check", "--strict")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def test_a_see_that_leads_nowhere_is_reported_like_a_cards(tmp_path):
|
|
38
|
+
root, _ = a_lab(tmp_path)
|
|
39
|
+
open(f"{root}/GLOSSARY.md", "a").write("\n## ghost\nNothing.\n- see: entries/not-there\n\n## stray\nNothing either.\n- see: elsewhere:/content/x/\n")
|
|
40
|
+
out = lab(root, "check", ok=False)
|
|
41
|
+
assert "GLOSSARY.md: ghost: see names the page entries/not-there, which is not in the library" in out
|
|
42
|
+
assert "GLOSSARY.md: stray: see names elsewhere:/content/x/, which is not a page of a library the charter names" in out
|
|
43
|
+
# the other library's page is missing while its folder is there
|
|
44
|
+
os.remove(tmp_path / "notes" / "content" / "concepts" / "lora" / "index.html")
|
|
45
|
+
os.rmdir(tmp_path / "notes" / "content" / "concepts" / "lora")
|
|
46
|
+
assert "LoRA: see names notes:/content/concepts/lora/, and the library notes holds no such page" in lab(root, "check", ok=False)
|
|
47
|
+
# the other library is not on the machine: a note, and a failure only when strict
|
|
48
|
+
os.rename(tmp_path / "notes", tmp_path / "away")
|
|
49
|
+
open(f"{root}/GLOSSARY.md", "w").write(ENTRIES)
|
|
50
|
+
out = lab(root, "check")
|
|
51
|
+
assert "the library notes is not here" in out and "the glossary name in it" in out and "problem(s)" not in out
|
|
52
|
+
assert "not everything could be checked here" in lab(root, "check", "--strict", ok=False)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def test_the_glossary_page_shows_avoid_in_small_type_and_see_as_a_link_and_the_tooltip_is_the_definition(tmp_path):
|
|
56
|
+
pytest.importorskip("folio.views")
|
|
57
|
+
from lab_kit.site import Provider
|
|
58
|
+
root, _ = a_lab(tmp_path)
|
|
59
|
+
page = Provider(root).get("glossary").main
|
|
60
|
+
assert '<span class="avoid">Avoid: gate, filter, policy</span>' in page
|
|
61
|
+
assert 'See: <a href="/content/entries/the-guard/">' in page and 'href="https://notes.example/content/concepts/lora/"' in page
|
|
62
|
+
goal = Provider(root).get("G1").main
|
|
63
|
+
tip = re.search(r'<span class="term" data-tip="([^"]*)"', page + goal + Provider(root).get("G1.Q1").main)
|
|
64
|
+
assert tip is None or "Avoid" not in tip.group(1)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def test_the_goal_lists_names_and_shows_the_glossarys_definitions(tmp_path):
|
|
68
|
+
pytest.importorskip("folio.views")
|
|
69
|
+
from lab_kit.site import Provider
|
|
70
|
+
root, _ = a_lab(tmp_path)
|
|
71
|
+
assert "the record is sound" in lab(root, "check", "--strict")
|
|
72
|
+
main = Provider(root).get("G1").main
|
|
73
|
+
assert "The words this lab uses" in main and "The part that reads every call and refuses the ones the contract forbids." in main and "One number on a grid." in main
|
|
74
|
+
assert "Avoid: gate, filter, policy" in main
|
|
75
|
+
shown = lab(root, "show", "G1")
|
|
76
|
+
assert "- guard: The part that reads every call" in shown and "avoid: gate, filter, policy" in shown and "see: entries/the-guard" in shown and "- field: One number on a grid." in shown
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def test_a_name_that_is_not_in_the_glossary_is_reported(tmp_path):
|
|
80
|
+
pytest.importorskip("folio.views")
|
|
81
|
+
from lab_kit.site import Provider
|
|
82
|
+
root, _ = a_lab(tmp_path, vocabulary="- guard\n- sieve")
|
|
83
|
+
out = lab(root, "check", ok=False)
|
|
84
|
+
assert "Vocabulary lists 'sieve', which is not a term in GLOSSARY.md: add it there first" in out and "'guard'" not in out
|
|
85
|
+
assert "- sieve: not in the glossary" in lab(root, "show", "G1")
|
|
86
|
+
assert "not in the glossary" in Provider(root).get("G1").main
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def test_the_old_form_is_reported_and_the_glossarys_text_is_shown_never_the_cards(tmp_path):
|
|
90
|
+
pytest.importorskip("folio.views")
|
|
91
|
+
from lab_kit.site import Provider
|
|
92
|
+
root, _ = a_lab(tmp_path, vocabulary="- field: a number the card made up\n- sieve: another made-up meaning")
|
|
93
|
+
out = lab(root, "check", ok=False)
|
|
94
|
+
assert "Vocabulary lists 'field' with a meaning: list the name only, `- field`" in out
|
|
95
|
+
assert "Vocabulary lists 'sieve', which is not a term in GLOSSARY.md" in out and "'sieve' with a meaning" not in out
|
|
96
|
+
main, shown = Provider(root).get("G1").main, lab(root, "show", "G1")
|
|
97
|
+
assert "One number on a grid." in main and "made up" not in main and "made-up" not in main
|
|
98
|
+
assert "- field: One number on a grid." in shown and "made up" not in shown and "made-up" not in shown
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def test_the_goal_a_new_lab_starts_with_has_an_empty_vocabulary_and_passes(tmp_path):
|
|
102
|
+
root = under(tmp_path, "lab")
|
|
103
|
+
open_question(root)
|
|
104
|
+
assert "## Vocabulary" in open(glob.glob(f"{root}/goals/G1-*/goal.md")[0]).read()
|
|
105
|
+
commit(root)
|
|
106
|
+
assert "Vocabulary" not in lab(root, "check")
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def test_markup_in_avoid_or_see_is_escaped(tmp_path):
|
|
110
|
+
pytest.importorskip("folio.views")
|
|
111
|
+
from lab_kit.site import Provider
|
|
112
|
+
P = 'x"><script>alert(1)</script>'
|
|
113
|
+
root, _ = a_lab(tmp_path, glossary=f"# Words\n\n## guard\nA guard.\n- avoid: {P}, <b>bold</b>\n- see: {P}\n\n## field\nA field.\n- see: other:{P}\n", vocabulary="- guard")
|
|
114
|
+
for page in (Provider(root).get("glossary").main, Provider(root).get("G1").main):
|
|
115
|
+
assert "<script>alert(1)" not in page and "<b>bold" not in page
|
|
116
|
+
assert "<script>" in Provider(root).get("glossary").main
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|