synapto-hub 0.1.0__py3-none-any.whl
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.
- synapto/__init__.py +1 -0
- synapto/bundle/__init__.py +1 -0
- synapto/bundle/decisions.py +86 -0
- synapto/bundle/models.py +346 -0
- synapto/bundle/validator.py +553 -0
- synapto/cli.py +287 -0
- synapto/environment.py +150 -0
- synapto/server/__init__.py +1 -0
- synapto/server/app.py +480 -0
- synapto/server/decide.py +120 -0
- synapto/server/kernels.py +472 -0
- synapto/server/lessons.py +148 -0
- synapto/server/notebook.py +195 -0
- synapto/server/testrunner.py +130 -0
- synapto/store.py +370 -0
- synapto/web/assets/abnfDiagram-VCTEODGH-BzgVtRmZ.js +1 -0
- synapto/web/assets/arc-DFmK96o1.js +1 -0
- synapto/web/assets/architecture-7GRP2DOG-zrp1H6CK.js +1 -0
- synapto/web/assets/architectureDiagram-5GKGNRK7-BuosZEl4.js +36 -0
- synapto/web/assets/array-BifhSqXX.js +1 -0
- synapto/web/assets/blockDiagram-I7D4REHJ-CudPrqYF.js +129 -0
- synapto/web/assets/c4Diagram-7LVT6UL2-Bx9Z0loF.js +38 -0
- synapto/web/assets/channel-BTnE_K1L.js +1 -0
- synapto/web/assets/chunk-2Q5K7J3B-C1jixKkw.js +1 -0
- synapto/web/assets/chunk-4HAMMTFA-Dz7u9Mh-.js +62 -0
- synapto/web/assets/chunk-5VM5RSS4-ZNzvKenW.js +15 -0
- synapto/web/assets/chunk-75Z2AOVW-OWQ1EWdD.js +2 -0
- synapto/web/assets/chunk-DU6HZSFF-BZ1HqZRP.js +127 -0
- synapto/web/assets/chunk-F27PBJKO-Ccq5rdp_.js +1 -0
- synapto/web/assets/chunk-FOHPRMQF-DzxwRta7.js +161 -0
- synapto/web/assets/chunk-GMAD6QVW-hqv2YP-U.js +72 -0
- synapto/web/assets/chunk-GVQU2GXP-BKNvYVBm.js +1 -0
- synapto/web/assets/chunk-IMKFNOWR-Bnq6oZC5.js +231 -0
- synapto/web/assets/chunk-JWPE2WC7-DVXcaiue.js +1 -0
- synapto/web/assets/chunk-L3NEJ4N5-5DkzRzcD.js +1 -0
- synapto/web/assets/chunk-OSK3NFVY-Dgs8_itk.js +10 -0
- synapto/web/assets/chunk-P2QGCYS3-BnDhWDjc.js +1 -0
- synapto/web/assets/chunk-POPQ4Y6H-CPRdMj-E.js +1 -0
- synapto/web/assets/chunk-PWAF6VOD-_mML4Cuz.js +1 -0
- synapto/web/assets/chunk-SHT3W25Y-Bxo-Luh8.js +168 -0
- synapto/web/assets/chunk-SVP7TREG-CjpZezPs.js +88 -0
- synapto/web/assets/chunk-TICWLB2K-B1wqeAp7.js +206 -0
- synapto/web/assets/chunk-XXDRQBXY-D6dcpnCk.js +1 -0
- synapto/web/assets/chunk-Y2CYZVJY-DsF7k-Jl.js +1 -0
- synapto/web/assets/classDiagram-ZZMXUADV-CwKhe2OP.js +1 -0
- synapto/web/assets/classDiagram-v2-VYDZK3BY-CwKhe2OP.js +1 -0
- synapto/web/assets/cose-bilkent-JH36ORCC-sM2bRXS2.js +1 -0
- synapto/web/assets/cynefin-OW5HDTMX-C4-KIuR1.js +1 -0
- synapto/web/assets/cynefinDiagram-5FMLGOSQ-Dhh1dIM1.js +62 -0
- synapto/web/assets/cytoscape.esm-Yq6u8L66.js +321 -0
- synapto/web/assets/dagre-C-rnJpZF.js +1 -0
- synapto/web/assets/dagre-GXQ25YYZ-C49ZzWYh.js +4 -0
- synapto/web/assets/defaultLocale-BFoDCU3G.js +1 -0
- synapto/web/assets/diagram-S7CK7UJ4-D9nA4BRW.js +30 -0
- synapto/web/assets/diagram-UQ7AKVKN-BJxJAwtj.js +41 -0
- synapto/web/assets/diagram-VSXAHHWV-ClFLSDld.js +3 -0
- synapto/web/assets/diagram-VX7I27RA-DN55aHJQ.js +24 -0
- synapto/web/assets/diagram-Z3DM3KII-Dpm1Nkf_.js +24 -0
- synapto/web/assets/dist-C9N7pTDR.js +1 -0
- synapto/web/assets/ebnfDiagram-PWID7BFC-DYKaLaoe.js +1 -0
- synapto/web/assets/erDiagram-RLTQ6QDP-86iSEqmb.js +99 -0
- synapto/web/assets/eventmodeling-NTZA5JFV-hYD5h-3e.js +1 -0
- synapto/web/assets/flowDiagram-HODETNUW-CHqQ1Ofw.js +1 -0
- synapto/web/assets/ganttDiagram-EL5Y4UJY-BO-2pK_a.js +292 -0
- synapto/web/assets/gitGraph-4MIJSDKK-Dckmqhtr.js +1 -0
- synapto/web/assets/gitGraphDiagram-WWUBYQGX-CjM7tH7V.js +106 -0
- synapto/web/assets/graphlib-DS17s2tU.js +1 -0
- synapto/web/assets/index-B7xe8VDD.js +67 -0
- synapto/web/assets/index-DrdFz88Z.css +1 -0
- synapto/web/assets/info-A6RAGUB7-Sp5Hh0xb.js +1 -0
- synapto/web/assets/infoDiagram-27XIBGKW-B5bXC6xW.js +2 -0
- synapto/web/assets/init-C-OQMol4.js +1 -0
- synapto/web/assets/inter-cyrillic-400-normal-HOLc17fK.woff +0 -0
- synapto/web/assets/inter-cyrillic-400-normal-obahsSVq.woff2 +0 -0
- synapto/web/assets/inter-cyrillic-500-normal-BasfLYem.woff2 +0 -0
- synapto/web/assets/inter-cyrillic-500-normal-CxZf_p3X.woff +0 -0
- synapto/web/assets/inter-cyrillic-600-normal-4D_pXhcN.woff +0 -0
- synapto/web/assets/inter-cyrillic-600-normal-CWCymEST.woff2 +0 -0
- synapto/web/assets/inter-cyrillic-ext-400-normal-BQZuk6qB.woff2 +0 -0
- synapto/web/assets/inter-cyrillic-ext-400-normal-DQukG94-.woff +0 -0
- synapto/web/assets/inter-cyrillic-ext-500-normal-B0yAr1jD.woff2 +0 -0
- synapto/web/assets/inter-cyrillic-ext-500-normal-BmqWE9Dz.woff +0 -0
- synapto/web/assets/inter-cyrillic-ext-600-normal-Bcila6Z-.woff +0 -0
- synapto/web/assets/inter-cyrillic-ext-600-normal-Dfes3d0z.woff2 +0 -0
- synapto/web/assets/inter-greek-400-normal-B4URO6DV.woff2 +0 -0
- synapto/web/assets/inter-greek-400-normal-q2sYcFCs.woff +0 -0
- synapto/web/assets/inter-greek-500-normal-BIZE56-Y.woff2 +0 -0
- synapto/web/assets/inter-greek-500-normal-Xzm54t5V.woff +0 -0
- synapto/web/assets/inter-greek-600-normal-BZpKdvQh.woff +0 -0
- synapto/web/assets/inter-greek-600-normal-plRanbMR.woff2 +0 -0
- synapto/web/assets/inter-greek-ext-400-normal-DGGRlc-M.woff2 +0 -0
- synapto/web/assets/inter-greek-ext-400-normal-KugGGMne.woff +0 -0
- synapto/web/assets/inter-greek-ext-500-normal-2j5mBUwD.woff +0 -0
- synapto/web/assets/inter-greek-ext-500-normal-C4iEst2y.woff2 +0 -0
- synapto/web/assets/inter-greek-ext-600-normal-B8X0CLgF.woff +0 -0
- synapto/web/assets/inter-greek-ext-600-normal-DRtmH8MT.woff2 +0 -0
- synapto/web/assets/inter-latin-400-normal-C38fXH4l.woff2 +0 -0
- synapto/web/assets/inter-latin-400-normal-CyCys3Eg.woff +0 -0
- synapto/web/assets/inter-latin-500-normal-BL9OpVg8.woff +0 -0
- synapto/web/assets/inter-latin-500-normal-Cerq10X2.woff2 +0 -0
- synapto/web/assets/inter-latin-600-normal-CiBQ2DWP.woff +0 -0
- synapto/web/assets/inter-latin-600-normal-LgqL8muc.woff2 +0 -0
- synapto/web/assets/inter-latin-ext-400-normal-77YHD8bZ.woff +0 -0
- synapto/web/assets/inter-latin-ext-400-normal-C1nco2VV.woff2 +0 -0
- synapto/web/assets/inter-latin-ext-500-normal-BxGbmqWO.woff +0 -0
- synapto/web/assets/inter-latin-ext-500-normal-CV4jyFjo.woff2 +0 -0
- synapto/web/assets/inter-latin-ext-600-normal-CIVaiw4L.woff +0 -0
- synapto/web/assets/inter-latin-ext-600-normal-D2bJ5OIk.woff2 +0 -0
- synapto/web/assets/inter-vietnamese-400-normal-Bbgyi5SW.woff +0 -0
- synapto/web/assets/inter-vietnamese-400-normal-DMkecbls.woff2 +0 -0
- synapto/web/assets/inter-vietnamese-500-normal-DOriooB6.woff2 +0 -0
- synapto/web/assets/inter-vietnamese-500-normal-mJboJaSs.woff +0 -0
- synapto/web/assets/inter-vietnamese-600-normal-BuLX-rYi.woff +0 -0
- synapto/web/assets/inter-vietnamese-600-normal-Cc8MFFhd.woff2 +0 -0
- synapto/web/assets/ishikawaDiagram-5VMMS53U-DlLxyIRL.js +70 -0
- synapto/web/assets/jetbrains-mono-cyrillic-400-normal-BEIGL1Tu.woff2 +0 -0
- synapto/web/assets/jetbrains-mono-cyrillic-400-normal-ugxPyKxw.woff +0 -0
- synapto/web/assets/jetbrains-mono-cyrillic-500-normal-DJqRU3vO.woff +0 -0
- synapto/web/assets/jetbrains-mono-cyrillic-500-normal-DmUKJPL_.woff2 +0 -0
- synapto/web/assets/jetbrains-mono-greek-400-normal-B9oWc5Lo.woff +0 -0
- synapto/web/assets/jetbrains-mono-greek-400-normal-C190GLew.woff2 +0 -0
- synapto/web/assets/jetbrains-mono-greek-500-normal-D7SFKleX.woff +0 -0
- synapto/web/assets/jetbrains-mono-greek-500-normal-JpySY46c.woff2 +0 -0
- synapto/web/assets/jetbrains-mono-latin-400-normal-6-qcROiO.woff +0 -0
- synapto/web/assets/jetbrains-mono-latin-400-normal-V6pRDFza.woff2 +0 -0
- synapto/web/assets/jetbrains-mono-latin-500-normal-BWZEU5yA.woff2 +0 -0
- synapto/web/assets/jetbrains-mono-latin-500-normal-CJOVTJB7.woff +0 -0
- synapto/web/assets/jetbrains-mono-latin-ext-400-normal-Bc8Ftmh3.woff2 +0 -0
- synapto/web/assets/jetbrains-mono-latin-ext-400-normal-fXTG6kC5.woff +0 -0
- synapto/web/assets/jetbrains-mono-latin-ext-500-normal-Cut-4mMH.woff2 +0 -0
- synapto/web/assets/jetbrains-mono-latin-ext-500-normal-ckzbgY84.woff +0 -0
- synapto/web/assets/jetbrains-mono-vietnamese-400-normal-CqNFfHCs.woff +0 -0
- synapto/web/assets/jetbrains-mono-vietnamese-500-normal-DNRqzVM1.woff +0 -0
- synapto/web/assets/journeyDiagram-3NMN7TZE-Cn7GmHUK.js +139 -0
- synapto/web/assets/kanban-definition-UXKFOSKX-CB63Fceu.js +89 -0
- synapto/web/assets/katex-ZlcWpGUi.js +257 -0
- synapto/web/assets/line-aNxvPf-1.js +1 -0
- synapto/web/assets/linear-CBnI93jZ.js +1 -0
- synapto/web/assets/mermaid-parser.core-N0YHHR1_.js +7 -0
- synapto/web/assets/mermaid.core-DBmdoC-V.js +44 -0
- synapto/web/assets/mindmap-definition-YA3MSWOX-BbJAJ-59.js +96 -0
- synapto/web/assets/montserrat-cyrillic-500-normal-CyGtXmN9.woff +0 -0
- synapto/web/assets/montserrat-cyrillic-500-normal-T0SG181k.woff2 +0 -0
- synapto/web/assets/montserrat-cyrillic-600-normal-CQEPC0hM.woff2 +0 -0
- synapto/web/assets/montserrat-cyrillic-600-normal-DUglwBrH.woff +0 -0
- synapto/web/assets/montserrat-cyrillic-ext-500-normal-11xBT7e1.woff2 +0 -0
- synapto/web/assets/montserrat-cyrillic-ext-500-normal-DOzfAZ45.woff +0 -0
- synapto/web/assets/montserrat-cyrillic-ext-600-normal-BtBW-rpm.woff2 +0 -0
- synapto/web/assets/montserrat-cyrillic-ext-600-normal-wReYPmz2.woff +0 -0
- synapto/web/assets/montserrat-latin-500-normal-DRFEGfly.woff2 +0 -0
- synapto/web/assets/montserrat-latin-500-normal-Dok2oTci.woff +0 -0
- synapto/web/assets/montserrat-latin-600-normal-CdhFl4lI.woff +0 -0
- synapto/web/assets/montserrat-latin-600-normal-UVxSCcoG.woff2 +0 -0
- synapto/web/assets/montserrat-latin-ext-500-normal-BKtbrd6n.woff2 +0 -0
- synapto/web/assets/montserrat-latin-ext-500-normal-DWPqqZgs.woff +0 -0
- synapto/web/assets/montserrat-latin-ext-600-normal-CSDhkhgS.woff +0 -0
- synapto/web/assets/montserrat-latin-ext-600-normal-DSkTqI9L.woff2 +0 -0
- synapto/web/assets/montserrat-vietnamese-500-normal-DpeZlV_K.woff +0 -0
- synapto/web/assets/montserrat-vietnamese-500-normal-NT-t8RG1.woff2 +0 -0
- synapto/web/assets/montserrat-vietnamese-600-normal-DKe6qT_E.woff2 +0 -0
- synapto/web/assets/montserrat-vietnamese-600-normal-SJ-HTWuM.woff +0 -0
- synapto/web/assets/ordinal-BDEzSJ7C.js +1 -0
- synapto/web/assets/packet-AYTQ26CC-DB9KOyQ4.js +1 -0
- synapto/web/assets/path-fybaL0A-.js +1 -0
- synapto/web/assets/pegDiagram-XKGWAZYB-DXlT0oJF.js +1 -0
- synapto/web/assets/pie-WAS4IAKB-sUrEgbC4.js +1 -0
- synapto/web/assets/pieDiagram-E7YTZNPT-Dt-p3aTR.js +39 -0
- synapto/web/assets/plotly.min-C0VrWA2L.js +3526 -0
- synapto/web/assets/quadrantDiagram-AXDQQJYC-CVhdtPco.js +7 -0
- synapto/web/assets/radar-RG4KPBEZ-DXQf618d.js +1 -0
- synapto/web/assets/railroad-74A4TZTK-D1T4x4-K.js +1 -0
- synapto/web/assets/railroad-abnf-HS5TGJTU-CErj6ZIe.js +1 -0
- synapto/web/assets/railroad-ebnf-LZEXJU2U-DEPob5Ru.js +1 -0
- synapto/web/assets/railroad-peg-WCYAUIDC-CH7u0Yg6.js +1 -0
- synapto/web/assets/railroadDiagram-O6MQD6OU-BDfEX1zC.js +1 -0
- synapto/web/assets/requirementDiagram-BXWQKSXE-0PWnZ_PF.js +84 -0
- synapto/web/assets/rough.esm-Dy-Kn_BL.js +1 -0
- synapto/web/assets/sankeyDiagram-P5KCCOFB-CzmXAlwy.js +40 -0
- synapto/web/assets/sequenceDiagram-WJ2MYXX4-C4kwKBBc.js +162 -0
- synapto/web/assets/sizeCapture-INFHLROL-3uHXrFqA.js +1 -0
- synapto/web/assets/src-DYcutCTp.js +1 -0
- synapto/web/assets/stateDiagram-D77RDMKH-DbpLbOeP.js +1 -0
- synapto/web/assets/stateDiagram-v2-MP3YSRHH-DNx3ipBZ.js +1 -0
- synapto/web/assets/swimlanes-42K2YHIH-DFi8XeS0.js +1 -0
- synapto/web/assets/swimlanesDiagram-VR7AAH4N-D1QzFjWS.js +8 -0
- synapto/web/assets/timeline-definition-24CTP7MA-CRE5CG6g.js +120 -0
- synapto/web/assets/treeView-Q6P3EWNA-DT2EnW9L.js +1 -0
- synapto/web/assets/treemap-WGGIJYW6-BCPoUUJE.js +1 -0
- synapto/web/assets/vennDiagram-4TSXK5OY-CE-jGbnB.js +34 -0
- synapto/web/assets/wardley-WFR3VGLG-CTplXEkW.js +1 -0
- synapto/web/assets/wardleyDiagram-VM6X3IG4-C_tavznA.js +78 -0
- synapto/web/assets/xychartDiagram-S5SC5T6Z-B4LGptT4.js +7 -0
- synapto/web/index.html +17 -0
- synapto/web/synapto-logo-lockup.png +0 -0
- synapto/web/synapto-mark.png +0 -0
- synapto_hub-0.1.0.dist-info/METADATA +125 -0
- synapto_hub-0.1.0.dist-info/RECORD +200 -0
- synapto_hub-0.1.0.dist-info/WHEEL +4 -0
- synapto_hub-0.1.0.dist-info/entry_points.txt +2 -0
- synapto_hub-0.1.0.dist-info/licenses/LICENSE +21 -0
synapto/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Synapto: interactive lessons from what your coding agent just built."""
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""The lesson bundle: the contract between the /debrief skill and the hub (spec §5)."""
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
"""Parse ``decisions.md`` (spec §5.3) into one record per decision.
|
|
2
|
+
|
|
3
|
+
The template is a ``## <title>`` section per decision with ``**Context:**``,
|
|
4
|
+
``**Options:**``, ``**Chosen:**``, ``**Why:**``, ``**Trade-offs:**`` and
|
|
5
|
+
``**ADR:**`` fields. The validator doesn't enforce it, so parsing is lenient:
|
|
6
|
+
anything it can't place stays available as the section's raw Markdown, and a
|
|
7
|
+
file without sections (the "no decisions were made" case) becomes a note.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import re
|
|
13
|
+
|
|
14
|
+
from pydantic import BaseModel
|
|
15
|
+
|
|
16
|
+
_SECTION = re.compile(r"^##[ \t]+(.+?)[ \t]*#*[ \t]*$", re.MULTILINE)
|
|
17
|
+
_FIELD = re.compile(r"^\*\*(Context|Options|Chosen|Why|Trade-offs|ADR):?\*\*:?[ \t]*", re.MULTILINE | re.IGNORECASE)
|
|
18
|
+
# "A — text", "(C — text)"; the dash may be an em dash, en dash or hyphen.
|
|
19
|
+
_OPTION = re.compile(r"^\(?\s*([A-Za-z0-9]{1,3})\s*[—–-]\s*(.+?)\s*\)?\.?$", re.DOTALL)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class DecisionOption(BaseModel):
|
|
23
|
+
id: str
|
|
24
|
+
label: str
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Decision(BaseModel):
|
|
28
|
+
title: str
|
|
29
|
+
context: str | None = None
|
|
30
|
+
options: list[DecisionOption] = []
|
|
31
|
+
chosen: str | None = None
|
|
32
|
+
why: str | None = None
|
|
33
|
+
tradeoffs: str | None = None
|
|
34
|
+
adr: str | None = None
|
|
35
|
+
body: str
|
|
36
|
+
"""The section's Markdown without its heading, for when the fields don't parse."""
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class Decisions(BaseModel):
|
|
40
|
+
decisions: list[Decision]
|
|
41
|
+
note: str | None = None
|
|
42
|
+
"""Text before the first section, e.g. "No architectural decisions were made."."""
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def parse_decisions(text: str) -> Decisions:
|
|
46
|
+
sections = list(_SECTION.finditer(text))
|
|
47
|
+
intro = text[: sections[0].start()] if sections else text
|
|
48
|
+
intro = re.sub(r"^#[ \t].*$", "", intro, flags=re.MULTILINE).strip() # drop a "# Decisions" title
|
|
49
|
+
decisions = []
|
|
50
|
+
for i, match in enumerate(sections):
|
|
51
|
+
end = sections[i + 1].start() if i + 1 < len(sections) else len(text)
|
|
52
|
+
decisions.append(_parse_section(match[1], text[match.end():end].strip()))
|
|
53
|
+
return Decisions(decisions=decisions, note=intro or None)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _parse_section(title: str, body: str) -> Decision:
|
|
57
|
+
fields: dict[str, str] = {}
|
|
58
|
+
marks = list(_FIELD.finditer(body))
|
|
59
|
+
for i, mark in enumerate(marks):
|
|
60
|
+
end = marks[i + 1].start() if i + 1 < len(marks) else len(body)
|
|
61
|
+
fields[mark[1].lower()] = " ".join(body[mark.end():end].split())
|
|
62
|
+
|
|
63
|
+
options = _parse_options(fields.get("options", ""))
|
|
64
|
+
chosen = fields.get("chosen")
|
|
65
|
+
if chosen and options:
|
|
66
|
+
# "B", "B — dict accumulation", "Option B"
|
|
67
|
+
ids = {o.id.lower(): o.id for o in options}
|
|
68
|
+
head = re.match(r"^(?:option\s+)?([A-Za-z0-9]{1,3})\b", chosen, re.IGNORECASE)
|
|
69
|
+
chosen = ids.get(head[1].lower()) if head else None
|
|
70
|
+
elif not options:
|
|
71
|
+
chosen = None
|
|
72
|
+
|
|
73
|
+
return Decision(
|
|
74
|
+
title=title, context=fields.get("context"), options=options, chosen=chosen,
|
|
75
|
+
why=fields.get("why"), tradeoffs=fields.get("trade-offs"), adr=fields.get("adr"), body=body,
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _parse_options(text: str) -> list[DecisionOption]:
|
|
80
|
+
options = []
|
|
81
|
+
for part in (p.strip() for p in text.split(";")):
|
|
82
|
+
match = _OPTION.match(part)
|
|
83
|
+
if match is None:
|
|
84
|
+
return [] # one unrecognised part means the list isn't in the template's shape
|
|
85
|
+
options.append(DecisionOption(id=match[1], label=match[2]))
|
|
86
|
+
return options
|
synapto/bundle/models.py
ADDED
|
@@ -0,0 +1,346 @@
|
|
|
1
|
+
"""Pydantic models for the files in a lesson bundle (spec §5).
|
|
2
|
+
|
|
3
|
+
Every model forbids unknown fields, so a misspelt key is reported instead of
|
|
4
|
+
silently ignored. Rules that only need one file are checked here; rules that
|
|
5
|
+
span files (references, fixtures, execution) live in ``validator``.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import re
|
|
11
|
+
from collections import Counter
|
|
12
|
+
from pathlib import PurePosixPath
|
|
13
|
+
from typing import Annotated, Literal
|
|
14
|
+
|
|
15
|
+
from pydantic import AfterValidator, AwareDatetime, BaseModel, ConfigDict, Field, model_validator
|
|
16
|
+
|
|
17
|
+
SCHEMA_VERSION = 1
|
|
18
|
+
|
|
19
|
+
_SOURCE_REF = re.compile(r"^(?P<path>[^:\s]+):(?P<start>\d+)(?:-(?P<end>\d+))?$")
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _non_empty(value: str) -> str:
|
|
23
|
+
if not value.strip():
|
|
24
|
+
raise ValueError("must not be empty")
|
|
25
|
+
return value
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _relative_path(value: str) -> str:
|
|
29
|
+
path = PurePosixPath(value)
|
|
30
|
+
if "\\" in value or path.is_absolute() or ".." in path.parts or not path.parts:
|
|
31
|
+
raise ValueError(f"must be a relative POSIX path inside the tree, got {value!r}")
|
|
32
|
+
return value
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _absolute_path(value: str) -> str:
|
|
36
|
+
# Accept Windows paths too, so a bundle written on Windows reads the same.
|
|
37
|
+
if not (value.startswith("/") or re.match(r"^[A-Za-z]:[\\/]", value)):
|
|
38
|
+
raise ValueError(f"must be an absolute path, got {value!r}")
|
|
39
|
+
return value
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _source_ref(value: str) -> str:
|
|
43
|
+
match = _SOURCE_REF.match(value)
|
|
44
|
+
if match is None:
|
|
45
|
+
raise ValueError(f"must look like 'path/to/file.py:12' or 'path/to/file.py:12-30', got {value!r}")
|
|
46
|
+
_relative_path(match["path"])
|
|
47
|
+
start, end = int(match["start"]), int(match["end"] or match["start"])
|
|
48
|
+
if start < 1 or end < start:
|
|
49
|
+
raise ValueError(f"line range {start}-{end} is invalid; lines start at 1 and end >= start")
|
|
50
|
+
return value
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
PARTS = ("explain", "decisions", "options", "notebook", "quiz", "rebuild")
|
|
54
|
+
"""The parts a lesson can have, in the order the hub shows them."""
|
|
55
|
+
Part = Literal["explain", "decisions", "options", "notebook", "quiz", "rebuild"]
|
|
56
|
+
DEBRIEF_PARTS: tuple[Part, ...] = ("explain", "decisions", "notebook", "quiz", "rebuild")
|
|
57
|
+
"""The parts a debrief lesson can have, and its default."""
|
|
58
|
+
DECISION_PARTS: tuple[Part, ...] = ("explain", "options", "quiz")
|
|
59
|
+
"""The parts a decision lesson can have (ADR-0008), and its default."""
|
|
60
|
+
RUNNABLE_PARTS: tuple[Part, ...] = ("notebook", "rebuild")
|
|
61
|
+
"""The parts whose code runs in the project interpreter."""
|
|
62
|
+
|
|
63
|
+
NonEmptyStr = Annotated[str, AfterValidator(_non_empty)]
|
|
64
|
+
RelativePath = Annotated[str, AfterValidator(_relative_path)]
|
|
65
|
+
AbsolutePath = Annotated[str, AfterValidator(_absolute_path)]
|
|
66
|
+
SourceRef = Annotated[str, AfterValidator(_source_ref)]
|
|
67
|
+
Identifier = Annotated[str, Field(pattern=r"^[A-Za-z_][A-Za-z0-9_]*$")]
|
|
68
|
+
Slug = Annotated[str, Field(pattern=r"^[a-z0-9]+(?:-[a-z0-9]+)*$")]
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def source_ref_path(ref: str) -> str:
|
|
72
|
+
"""The file part of a valid source ref: ``'src/a.py:3-9'`` -> ``'src/a.py'``."""
|
|
73
|
+
return ref.rsplit(":", 1)[0]
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _duplicates(values: list[str]) -> list[str]:
|
|
77
|
+
return sorted(v for v, n in Counter(values).items() if n > 1)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
class _Model(BaseModel):
|
|
81
|
+
model_config = ConfigDict(extra="forbid")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
# --- lesson.json -------------------------------------------------------------
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class SourceFile(_Model):
|
|
88
|
+
path: RelativePath
|
|
89
|
+
sha256: Annotated[str, Field(pattern=r"^[0-9a-f]{64}$")]
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
class Source(_Model):
|
|
93
|
+
repo_path: AbsolutePath
|
|
94
|
+
remote: str | None = None
|
|
95
|
+
branch: str | None = None
|
|
96
|
+
base_commit: str | None = None
|
|
97
|
+
head_commit: str | None = None
|
|
98
|
+
includes_uncommitted: bool = False
|
|
99
|
+
files: list[SourceFile]
|
|
100
|
+
"""Every file a ``source_ref`` points into; at least one in a debrief lesson."""
|
|
101
|
+
|
|
102
|
+
@model_validator(mode="after")
|
|
103
|
+
def _unique_paths(self) -> Source:
|
|
104
|
+
if dupes := _duplicates([f.path for f in self.files]):
|
|
105
|
+
raise ValueError(f"files lists these paths more than once: {', '.join(dupes)}")
|
|
106
|
+
return self
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
class Environment(_Model):
|
|
110
|
+
python: AbsolutePath
|
|
111
|
+
python_version: NonEmptyStr
|
|
112
|
+
cwd: AbsolutePath
|
|
113
|
+
extra_sys_path: list[RelativePath] = []
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class DataSlot(_Model):
|
|
117
|
+
name: Identifier
|
|
118
|
+
kind: Literal["file", "dir", "string", "number"]
|
|
119
|
+
description: NonEmptyStr
|
|
120
|
+
default: str | int | float | None = None
|
|
121
|
+
required: bool = False
|
|
122
|
+
|
|
123
|
+
@model_validator(mode="after")
|
|
124
|
+
def _default_matches_kind(self) -> DataSlot:
|
|
125
|
+
value = self.default
|
|
126
|
+
if value is None:
|
|
127
|
+
return self
|
|
128
|
+
if self.kind == "number":
|
|
129
|
+
if isinstance(value, bool) or not isinstance(value, (int, float)):
|
|
130
|
+
raise ValueError(f"default of a number slot must be a JSON number, got {value!r}")
|
|
131
|
+
elif not isinstance(value, str):
|
|
132
|
+
raise ValueError(f"default of a {self.kind} slot must be a string, got {value!r}")
|
|
133
|
+
elif self.kind in ("file", "dir"):
|
|
134
|
+
try:
|
|
135
|
+
_relative_path(value)
|
|
136
|
+
except ValueError:
|
|
137
|
+
raise ValueError(
|
|
138
|
+
f"default of a {self.kind} slot must be a path inside the bundle "
|
|
139
|
+
f"(e.g. 'fixtures/sample.csv'), got {value!r}"
|
|
140
|
+
) from None
|
|
141
|
+
return self
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class Lesson(_Model):
|
|
145
|
+
schema_version: Literal[1]
|
|
146
|
+
kind: Literal["debrief", "decision"] = "debrief"
|
|
147
|
+
"""``debrief`` looks back on built code; ``decision`` teaches a choice before it's built (ADR-0008)."""
|
|
148
|
+
id: Annotated[str, Field(pattern=r"^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$")]
|
|
149
|
+
title: NonEmptyStr
|
|
150
|
+
summary: NonEmptyStr
|
|
151
|
+
created_at: AwareDatetime
|
|
152
|
+
difficulty: Literal["beginner", "intermediate", "advanced"]
|
|
153
|
+
concepts: Annotated[list[NonEmptyStr], Field(min_length=1)]
|
|
154
|
+
prerequisites: list[NonEmptyStr] = []
|
|
155
|
+
question: NonEmptyStr | None = None
|
|
156
|
+
"""A decision lesson's question, in the developer's words."""
|
|
157
|
+
mode: Literal["guided", "open"] | None = None
|
|
158
|
+
"""A decision lesson's mode: lead to the recommendation, or let the developer decide."""
|
|
159
|
+
source: Source | None = None
|
|
160
|
+
"""Required in a debrief lesson; a decision lesson may have no repo yet."""
|
|
161
|
+
environment: Environment | None = None
|
|
162
|
+
"""Required when the lesson has a runnable part."""
|
|
163
|
+
data_slots: list[DataSlot] = []
|
|
164
|
+
parts: Annotated[list[Part], Field(min_length=1)]
|
|
165
|
+
"""The parts the developer chose; each has its own file(s) in the bundle.
|
|
166
|
+
|
|
167
|
+
Defaults to every part of the lesson's kind.
|
|
168
|
+
"""
|
|
169
|
+
|
|
170
|
+
@model_validator(mode="before")
|
|
171
|
+
@classmethod
|
|
172
|
+
def _default_parts(cls, data: object) -> object:
|
|
173
|
+
if isinstance(data, dict) and "parts" not in data:
|
|
174
|
+
parts = DECISION_PARTS if data.get("kind") == "decision" else DEBRIEF_PARTS
|
|
175
|
+
data = {**data, "parts": list(parts)}
|
|
176
|
+
return data
|
|
177
|
+
|
|
178
|
+
@model_validator(mode="after")
|
|
179
|
+
def _consistent(self) -> Lesson:
|
|
180
|
+
if dupes := _duplicates([s.name for s in self.data_slots]):
|
|
181
|
+
raise ValueError(f"data_slots has duplicate names: {', '.join(dupes)}")
|
|
182
|
+
if dupes := _duplicates(list(self.parts)):
|
|
183
|
+
raise ValueError(f"parts lists these more than once: {', '.join(dupes)}")
|
|
184
|
+
allowed = DECISION_PARTS if self.kind == "decision" else DEBRIEF_PARTS
|
|
185
|
+
if wrong := [p for p in self.parts if p not in allowed]:
|
|
186
|
+
raise ValueError(f"a {self.kind} lesson can't have the part(s) {', '.join(wrong)}; "
|
|
187
|
+
f"its parts are {', '.join(allowed)}")
|
|
188
|
+
if self.kind == "decision":
|
|
189
|
+
missing = [f for f in ("question", "mode") if getattr(self, f) is None]
|
|
190
|
+
if missing:
|
|
191
|
+
raise ValueError(f"a decision lesson needs {' and '.join(missing)}")
|
|
192
|
+
if "options" not in self.parts:
|
|
193
|
+
raise ValueError("a decision lesson needs the 'options' part")
|
|
194
|
+
else:
|
|
195
|
+
if self.question is not None or self.mode is not None:
|
|
196
|
+
raise ValueError("question and mode belong to decision lessons; remove them, "
|
|
197
|
+
"or set kind to 'decision'")
|
|
198
|
+
if self.source is None:
|
|
199
|
+
raise ValueError("a debrief lesson needs source")
|
|
200
|
+
if not self.source.files:
|
|
201
|
+
raise ValueError("source.files must list at least one file in a debrief lesson")
|
|
202
|
+
if self.environment is None and any(p in self.parts for p in RUNNABLE_PARTS):
|
|
203
|
+
raise ValueError("environment is required when parts has notebook or rebuild")
|
|
204
|
+
return self
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
# --- options.json (decision lessons) ------------------------------------------
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
class Criterion(_Model):
|
|
211
|
+
id: Slug
|
|
212
|
+
name: NonEmptyStr
|
|
213
|
+
description: NonEmptyStr
|
|
214
|
+
weight: Annotated[int, Field(ge=1, le=3)]
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
class Link(_Model):
|
|
218
|
+
title: NonEmptyStr
|
|
219
|
+
url: Annotated[str, Field(pattern=r"^https?://\S+$")]
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
class Candidate(_Model):
|
|
223
|
+
id: Slug
|
|
224
|
+
name: NonEmptyStr
|
|
225
|
+
summary: NonEmptyStr
|
|
226
|
+
strengths: Annotated[list[NonEmptyStr], Field(min_length=1)]
|
|
227
|
+
weaknesses: Annotated[list[NonEmptyStr], Field(min_length=1)]
|
|
228
|
+
fits_when: NonEmptyStr
|
|
229
|
+
scores: dict[str, Annotated[int, Field(ge=1, le=5)]]
|
|
230
|
+
"""Criterion id -> 1 (poor) to 5 (excellent)."""
|
|
231
|
+
links: list[Link] = []
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
class Recommendation(_Model):
|
|
235
|
+
option: NonEmptyStr
|
|
236
|
+
why: NonEmptyStr
|
|
237
|
+
trade_offs: NonEmptyStr
|
|
238
|
+
would_change_if: NonEmptyStr
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
class Options(_Model):
|
|
242
|
+
criteria: Annotated[list[Criterion], Field(min_length=2, max_length=8)]
|
|
243
|
+
options: Annotated[list[Candidate], Field(min_length=2, max_length=5)]
|
|
244
|
+
recommendation: Recommendation
|
|
245
|
+
|
|
246
|
+
@model_validator(mode="after")
|
|
247
|
+
def _references(self) -> Options:
|
|
248
|
+
criteria = [c.id for c in self.criteria]
|
|
249
|
+
if dupes := _duplicates(criteria):
|
|
250
|
+
raise ValueError(f"duplicate criterion ids: {', '.join(dupes)}")
|
|
251
|
+
ids = [o.id for o in self.options]
|
|
252
|
+
if dupes := _duplicates(ids):
|
|
253
|
+
raise ValueError(f"duplicate option ids: {', '.join(dupes)}")
|
|
254
|
+
for option in self.options:
|
|
255
|
+
if missing := [c for c in criteria if c not in option.scores]:
|
|
256
|
+
raise ValueError(f"option {option.id!r} has no score for: {', '.join(missing)}")
|
|
257
|
+
if unknown := sorted(set(option.scores) - set(criteria)):
|
|
258
|
+
raise ValueError(f"option {option.id!r} scores unknown criteria: {', '.join(unknown)}")
|
|
259
|
+
if self.recommendation.option not in ids:
|
|
260
|
+
raise ValueError(f"recommendation.option {self.recommendation.option!r} is not one of "
|
|
261
|
+
f"the option ids ({', '.join(ids)})")
|
|
262
|
+
return self
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
# --- a review verdict (``synapto decision verdict``) ---------------------------
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
class Challenge(_Model):
|
|
269
|
+
question: NonEmptyStr
|
|
270
|
+
response: NonEmptyStr
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
class Verdict(_Model):
|
|
274
|
+
final_option: NonEmptyStr
|
|
275
|
+
"""The option the developer settled on in the review; may differ from their recorded choice."""
|
|
276
|
+
challenges: Annotated[list[Challenge], Field(min_length=1)]
|
|
277
|
+
opinion: NonEmptyStr
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
# --- quiz.json -----------------------------------------------------------------
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
class QuizOption(_Model):
|
|
284
|
+
id: NonEmptyStr
|
|
285
|
+
text: NonEmptyStr
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
class QuizQuestion(_Model):
|
|
289
|
+
id: NonEmptyStr
|
|
290
|
+
prompt: NonEmptyStr
|
|
291
|
+
options: list[QuizOption]
|
|
292
|
+
correct: str
|
|
293
|
+
explanation: NonEmptyStr
|
|
294
|
+
concept: NonEmptyStr | None = None
|
|
295
|
+
source_ref: SourceRef | None = None
|
|
296
|
+
|
|
297
|
+
@model_validator(mode="after")
|
|
298
|
+
def _options(self) -> QuizQuestion:
|
|
299
|
+
ids = [o.id for o in self.options]
|
|
300
|
+
if len(ids) < 3:
|
|
301
|
+
raise ValueError(f"needs at least 3 options, has {len(ids)}")
|
|
302
|
+
if dupes := _duplicates(ids):
|
|
303
|
+
raise ValueError(f"duplicate option ids: {', '.join(dupes)}")
|
|
304
|
+
if self.correct not in ids:
|
|
305
|
+
raise ValueError(f"correct {self.correct!r} is not one of the option ids ({', '.join(ids)})")
|
|
306
|
+
return self
|
|
307
|
+
|
|
308
|
+
|
|
309
|
+
class Quiz(_Model):
|
|
310
|
+
questions: Annotated[list[QuizQuestion], Field(min_length=5, max_length=10)]
|
|
311
|
+
|
|
312
|
+
@model_validator(mode="after")
|
|
313
|
+
def _unique_ids(self) -> Quiz:
|
|
314
|
+
if dupes := _duplicates([q.id for q in self.questions]):
|
|
315
|
+
raise ValueError(f"duplicate question ids: {', '.join(dupes)}")
|
|
316
|
+
return self
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
# --- exercises/<id>/exercise.json ----------------------------------------------
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
class Exercise(_Model):
|
|
323
|
+
id: Annotated[str, Field(pattern=r"^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$")]
|
|
324
|
+
title: NonEmptyStr
|
|
325
|
+
function: Identifier
|
|
326
|
+
prompt: NonEmptyStr
|
|
327
|
+
difficulty: Literal["easy", "medium", "hard"]
|
|
328
|
+
hints: list[NonEmptyStr] = []
|
|
329
|
+
source_ref: SourceRef
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
# --- notebook.ipynb cell metadata (``metadata.synapto``) -----------------------
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
class CellMeta(_Model):
|
|
336
|
+
role: Literal["setup", "function", "demo", "explain"]
|
|
337
|
+
function: Identifier | None = None
|
|
338
|
+
source_ref: SourceRef | None = None
|
|
339
|
+
hidden: bool = False
|
|
340
|
+
editable: bool = True
|
|
341
|
+
|
|
342
|
+
@model_validator(mode="after")
|
|
343
|
+
def _function_fields(self) -> CellMeta:
|
|
344
|
+
if self.role == "function" and (self.function is None or self.source_ref is None):
|
|
345
|
+
raise ValueError("a function cell needs both 'function' and 'source_ref'")
|
|
346
|
+
return self
|