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.
Files changed (200) hide show
  1. synapto/__init__.py +1 -0
  2. synapto/bundle/__init__.py +1 -0
  3. synapto/bundle/decisions.py +86 -0
  4. synapto/bundle/models.py +346 -0
  5. synapto/bundle/validator.py +553 -0
  6. synapto/cli.py +287 -0
  7. synapto/environment.py +150 -0
  8. synapto/server/__init__.py +1 -0
  9. synapto/server/app.py +480 -0
  10. synapto/server/decide.py +120 -0
  11. synapto/server/kernels.py +472 -0
  12. synapto/server/lessons.py +148 -0
  13. synapto/server/notebook.py +195 -0
  14. synapto/server/testrunner.py +130 -0
  15. synapto/store.py +370 -0
  16. synapto/web/assets/abnfDiagram-VCTEODGH-BzgVtRmZ.js +1 -0
  17. synapto/web/assets/arc-DFmK96o1.js +1 -0
  18. synapto/web/assets/architecture-7GRP2DOG-zrp1H6CK.js +1 -0
  19. synapto/web/assets/architectureDiagram-5GKGNRK7-BuosZEl4.js +36 -0
  20. synapto/web/assets/array-BifhSqXX.js +1 -0
  21. synapto/web/assets/blockDiagram-I7D4REHJ-CudPrqYF.js +129 -0
  22. synapto/web/assets/c4Diagram-7LVT6UL2-Bx9Z0loF.js +38 -0
  23. synapto/web/assets/channel-BTnE_K1L.js +1 -0
  24. synapto/web/assets/chunk-2Q5K7J3B-C1jixKkw.js +1 -0
  25. synapto/web/assets/chunk-4HAMMTFA-Dz7u9Mh-.js +62 -0
  26. synapto/web/assets/chunk-5VM5RSS4-ZNzvKenW.js +15 -0
  27. synapto/web/assets/chunk-75Z2AOVW-OWQ1EWdD.js +2 -0
  28. synapto/web/assets/chunk-DU6HZSFF-BZ1HqZRP.js +127 -0
  29. synapto/web/assets/chunk-F27PBJKO-Ccq5rdp_.js +1 -0
  30. synapto/web/assets/chunk-FOHPRMQF-DzxwRta7.js +161 -0
  31. synapto/web/assets/chunk-GMAD6QVW-hqv2YP-U.js +72 -0
  32. synapto/web/assets/chunk-GVQU2GXP-BKNvYVBm.js +1 -0
  33. synapto/web/assets/chunk-IMKFNOWR-Bnq6oZC5.js +231 -0
  34. synapto/web/assets/chunk-JWPE2WC7-DVXcaiue.js +1 -0
  35. synapto/web/assets/chunk-L3NEJ4N5-5DkzRzcD.js +1 -0
  36. synapto/web/assets/chunk-OSK3NFVY-Dgs8_itk.js +10 -0
  37. synapto/web/assets/chunk-P2QGCYS3-BnDhWDjc.js +1 -0
  38. synapto/web/assets/chunk-POPQ4Y6H-CPRdMj-E.js +1 -0
  39. synapto/web/assets/chunk-PWAF6VOD-_mML4Cuz.js +1 -0
  40. synapto/web/assets/chunk-SHT3W25Y-Bxo-Luh8.js +168 -0
  41. synapto/web/assets/chunk-SVP7TREG-CjpZezPs.js +88 -0
  42. synapto/web/assets/chunk-TICWLB2K-B1wqeAp7.js +206 -0
  43. synapto/web/assets/chunk-XXDRQBXY-D6dcpnCk.js +1 -0
  44. synapto/web/assets/chunk-Y2CYZVJY-DsF7k-Jl.js +1 -0
  45. synapto/web/assets/classDiagram-ZZMXUADV-CwKhe2OP.js +1 -0
  46. synapto/web/assets/classDiagram-v2-VYDZK3BY-CwKhe2OP.js +1 -0
  47. synapto/web/assets/cose-bilkent-JH36ORCC-sM2bRXS2.js +1 -0
  48. synapto/web/assets/cynefin-OW5HDTMX-C4-KIuR1.js +1 -0
  49. synapto/web/assets/cynefinDiagram-5FMLGOSQ-Dhh1dIM1.js +62 -0
  50. synapto/web/assets/cytoscape.esm-Yq6u8L66.js +321 -0
  51. synapto/web/assets/dagre-C-rnJpZF.js +1 -0
  52. synapto/web/assets/dagre-GXQ25YYZ-C49ZzWYh.js +4 -0
  53. synapto/web/assets/defaultLocale-BFoDCU3G.js +1 -0
  54. synapto/web/assets/diagram-S7CK7UJ4-D9nA4BRW.js +30 -0
  55. synapto/web/assets/diagram-UQ7AKVKN-BJxJAwtj.js +41 -0
  56. synapto/web/assets/diagram-VSXAHHWV-ClFLSDld.js +3 -0
  57. synapto/web/assets/diagram-VX7I27RA-DN55aHJQ.js +24 -0
  58. synapto/web/assets/diagram-Z3DM3KII-Dpm1Nkf_.js +24 -0
  59. synapto/web/assets/dist-C9N7pTDR.js +1 -0
  60. synapto/web/assets/ebnfDiagram-PWID7BFC-DYKaLaoe.js +1 -0
  61. synapto/web/assets/erDiagram-RLTQ6QDP-86iSEqmb.js +99 -0
  62. synapto/web/assets/eventmodeling-NTZA5JFV-hYD5h-3e.js +1 -0
  63. synapto/web/assets/flowDiagram-HODETNUW-CHqQ1Ofw.js +1 -0
  64. synapto/web/assets/ganttDiagram-EL5Y4UJY-BO-2pK_a.js +292 -0
  65. synapto/web/assets/gitGraph-4MIJSDKK-Dckmqhtr.js +1 -0
  66. synapto/web/assets/gitGraphDiagram-WWUBYQGX-CjM7tH7V.js +106 -0
  67. synapto/web/assets/graphlib-DS17s2tU.js +1 -0
  68. synapto/web/assets/index-B7xe8VDD.js +67 -0
  69. synapto/web/assets/index-DrdFz88Z.css +1 -0
  70. synapto/web/assets/info-A6RAGUB7-Sp5Hh0xb.js +1 -0
  71. synapto/web/assets/infoDiagram-27XIBGKW-B5bXC6xW.js +2 -0
  72. synapto/web/assets/init-C-OQMol4.js +1 -0
  73. synapto/web/assets/inter-cyrillic-400-normal-HOLc17fK.woff +0 -0
  74. synapto/web/assets/inter-cyrillic-400-normal-obahsSVq.woff2 +0 -0
  75. synapto/web/assets/inter-cyrillic-500-normal-BasfLYem.woff2 +0 -0
  76. synapto/web/assets/inter-cyrillic-500-normal-CxZf_p3X.woff +0 -0
  77. synapto/web/assets/inter-cyrillic-600-normal-4D_pXhcN.woff +0 -0
  78. synapto/web/assets/inter-cyrillic-600-normal-CWCymEST.woff2 +0 -0
  79. synapto/web/assets/inter-cyrillic-ext-400-normal-BQZuk6qB.woff2 +0 -0
  80. synapto/web/assets/inter-cyrillic-ext-400-normal-DQukG94-.woff +0 -0
  81. synapto/web/assets/inter-cyrillic-ext-500-normal-B0yAr1jD.woff2 +0 -0
  82. synapto/web/assets/inter-cyrillic-ext-500-normal-BmqWE9Dz.woff +0 -0
  83. synapto/web/assets/inter-cyrillic-ext-600-normal-Bcila6Z-.woff +0 -0
  84. synapto/web/assets/inter-cyrillic-ext-600-normal-Dfes3d0z.woff2 +0 -0
  85. synapto/web/assets/inter-greek-400-normal-B4URO6DV.woff2 +0 -0
  86. synapto/web/assets/inter-greek-400-normal-q2sYcFCs.woff +0 -0
  87. synapto/web/assets/inter-greek-500-normal-BIZE56-Y.woff2 +0 -0
  88. synapto/web/assets/inter-greek-500-normal-Xzm54t5V.woff +0 -0
  89. synapto/web/assets/inter-greek-600-normal-BZpKdvQh.woff +0 -0
  90. synapto/web/assets/inter-greek-600-normal-plRanbMR.woff2 +0 -0
  91. synapto/web/assets/inter-greek-ext-400-normal-DGGRlc-M.woff2 +0 -0
  92. synapto/web/assets/inter-greek-ext-400-normal-KugGGMne.woff +0 -0
  93. synapto/web/assets/inter-greek-ext-500-normal-2j5mBUwD.woff +0 -0
  94. synapto/web/assets/inter-greek-ext-500-normal-C4iEst2y.woff2 +0 -0
  95. synapto/web/assets/inter-greek-ext-600-normal-B8X0CLgF.woff +0 -0
  96. synapto/web/assets/inter-greek-ext-600-normal-DRtmH8MT.woff2 +0 -0
  97. synapto/web/assets/inter-latin-400-normal-C38fXH4l.woff2 +0 -0
  98. synapto/web/assets/inter-latin-400-normal-CyCys3Eg.woff +0 -0
  99. synapto/web/assets/inter-latin-500-normal-BL9OpVg8.woff +0 -0
  100. synapto/web/assets/inter-latin-500-normal-Cerq10X2.woff2 +0 -0
  101. synapto/web/assets/inter-latin-600-normal-CiBQ2DWP.woff +0 -0
  102. synapto/web/assets/inter-latin-600-normal-LgqL8muc.woff2 +0 -0
  103. synapto/web/assets/inter-latin-ext-400-normal-77YHD8bZ.woff +0 -0
  104. synapto/web/assets/inter-latin-ext-400-normal-C1nco2VV.woff2 +0 -0
  105. synapto/web/assets/inter-latin-ext-500-normal-BxGbmqWO.woff +0 -0
  106. synapto/web/assets/inter-latin-ext-500-normal-CV4jyFjo.woff2 +0 -0
  107. synapto/web/assets/inter-latin-ext-600-normal-CIVaiw4L.woff +0 -0
  108. synapto/web/assets/inter-latin-ext-600-normal-D2bJ5OIk.woff2 +0 -0
  109. synapto/web/assets/inter-vietnamese-400-normal-Bbgyi5SW.woff +0 -0
  110. synapto/web/assets/inter-vietnamese-400-normal-DMkecbls.woff2 +0 -0
  111. synapto/web/assets/inter-vietnamese-500-normal-DOriooB6.woff2 +0 -0
  112. synapto/web/assets/inter-vietnamese-500-normal-mJboJaSs.woff +0 -0
  113. synapto/web/assets/inter-vietnamese-600-normal-BuLX-rYi.woff +0 -0
  114. synapto/web/assets/inter-vietnamese-600-normal-Cc8MFFhd.woff2 +0 -0
  115. synapto/web/assets/ishikawaDiagram-5VMMS53U-DlLxyIRL.js +70 -0
  116. synapto/web/assets/jetbrains-mono-cyrillic-400-normal-BEIGL1Tu.woff2 +0 -0
  117. synapto/web/assets/jetbrains-mono-cyrillic-400-normal-ugxPyKxw.woff +0 -0
  118. synapto/web/assets/jetbrains-mono-cyrillic-500-normal-DJqRU3vO.woff +0 -0
  119. synapto/web/assets/jetbrains-mono-cyrillic-500-normal-DmUKJPL_.woff2 +0 -0
  120. synapto/web/assets/jetbrains-mono-greek-400-normal-B9oWc5Lo.woff +0 -0
  121. synapto/web/assets/jetbrains-mono-greek-400-normal-C190GLew.woff2 +0 -0
  122. synapto/web/assets/jetbrains-mono-greek-500-normal-D7SFKleX.woff +0 -0
  123. synapto/web/assets/jetbrains-mono-greek-500-normal-JpySY46c.woff2 +0 -0
  124. synapto/web/assets/jetbrains-mono-latin-400-normal-6-qcROiO.woff +0 -0
  125. synapto/web/assets/jetbrains-mono-latin-400-normal-V6pRDFza.woff2 +0 -0
  126. synapto/web/assets/jetbrains-mono-latin-500-normal-BWZEU5yA.woff2 +0 -0
  127. synapto/web/assets/jetbrains-mono-latin-500-normal-CJOVTJB7.woff +0 -0
  128. synapto/web/assets/jetbrains-mono-latin-ext-400-normal-Bc8Ftmh3.woff2 +0 -0
  129. synapto/web/assets/jetbrains-mono-latin-ext-400-normal-fXTG6kC5.woff +0 -0
  130. synapto/web/assets/jetbrains-mono-latin-ext-500-normal-Cut-4mMH.woff2 +0 -0
  131. synapto/web/assets/jetbrains-mono-latin-ext-500-normal-ckzbgY84.woff +0 -0
  132. synapto/web/assets/jetbrains-mono-vietnamese-400-normal-CqNFfHCs.woff +0 -0
  133. synapto/web/assets/jetbrains-mono-vietnamese-500-normal-DNRqzVM1.woff +0 -0
  134. synapto/web/assets/journeyDiagram-3NMN7TZE-Cn7GmHUK.js +139 -0
  135. synapto/web/assets/kanban-definition-UXKFOSKX-CB63Fceu.js +89 -0
  136. synapto/web/assets/katex-ZlcWpGUi.js +257 -0
  137. synapto/web/assets/line-aNxvPf-1.js +1 -0
  138. synapto/web/assets/linear-CBnI93jZ.js +1 -0
  139. synapto/web/assets/mermaid-parser.core-N0YHHR1_.js +7 -0
  140. synapto/web/assets/mermaid.core-DBmdoC-V.js +44 -0
  141. synapto/web/assets/mindmap-definition-YA3MSWOX-BbJAJ-59.js +96 -0
  142. synapto/web/assets/montserrat-cyrillic-500-normal-CyGtXmN9.woff +0 -0
  143. synapto/web/assets/montserrat-cyrillic-500-normal-T0SG181k.woff2 +0 -0
  144. synapto/web/assets/montserrat-cyrillic-600-normal-CQEPC0hM.woff2 +0 -0
  145. synapto/web/assets/montserrat-cyrillic-600-normal-DUglwBrH.woff +0 -0
  146. synapto/web/assets/montserrat-cyrillic-ext-500-normal-11xBT7e1.woff2 +0 -0
  147. synapto/web/assets/montserrat-cyrillic-ext-500-normal-DOzfAZ45.woff +0 -0
  148. synapto/web/assets/montserrat-cyrillic-ext-600-normal-BtBW-rpm.woff2 +0 -0
  149. synapto/web/assets/montserrat-cyrillic-ext-600-normal-wReYPmz2.woff +0 -0
  150. synapto/web/assets/montserrat-latin-500-normal-DRFEGfly.woff2 +0 -0
  151. synapto/web/assets/montserrat-latin-500-normal-Dok2oTci.woff +0 -0
  152. synapto/web/assets/montserrat-latin-600-normal-CdhFl4lI.woff +0 -0
  153. synapto/web/assets/montserrat-latin-600-normal-UVxSCcoG.woff2 +0 -0
  154. synapto/web/assets/montserrat-latin-ext-500-normal-BKtbrd6n.woff2 +0 -0
  155. synapto/web/assets/montserrat-latin-ext-500-normal-DWPqqZgs.woff +0 -0
  156. synapto/web/assets/montserrat-latin-ext-600-normal-CSDhkhgS.woff +0 -0
  157. synapto/web/assets/montserrat-latin-ext-600-normal-DSkTqI9L.woff2 +0 -0
  158. synapto/web/assets/montserrat-vietnamese-500-normal-DpeZlV_K.woff +0 -0
  159. synapto/web/assets/montserrat-vietnamese-500-normal-NT-t8RG1.woff2 +0 -0
  160. synapto/web/assets/montserrat-vietnamese-600-normal-DKe6qT_E.woff2 +0 -0
  161. synapto/web/assets/montserrat-vietnamese-600-normal-SJ-HTWuM.woff +0 -0
  162. synapto/web/assets/ordinal-BDEzSJ7C.js +1 -0
  163. synapto/web/assets/packet-AYTQ26CC-DB9KOyQ4.js +1 -0
  164. synapto/web/assets/path-fybaL0A-.js +1 -0
  165. synapto/web/assets/pegDiagram-XKGWAZYB-DXlT0oJF.js +1 -0
  166. synapto/web/assets/pie-WAS4IAKB-sUrEgbC4.js +1 -0
  167. synapto/web/assets/pieDiagram-E7YTZNPT-Dt-p3aTR.js +39 -0
  168. synapto/web/assets/plotly.min-C0VrWA2L.js +3526 -0
  169. synapto/web/assets/quadrantDiagram-AXDQQJYC-CVhdtPco.js +7 -0
  170. synapto/web/assets/radar-RG4KPBEZ-DXQf618d.js +1 -0
  171. synapto/web/assets/railroad-74A4TZTK-D1T4x4-K.js +1 -0
  172. synapto/web/assets/railroad-abnf-HS5TGJTU-CErj6ZIe.js +1 -0
  173. synapto/web/assets/railroad-ebnf-LZEXJU2U-DEPob5Ru.js +1 -0
  174. synapto/web/assets/railroad-peg-WCYAUIDC-CH7u0Yg6.js +1 -0
  175. synapto/web/assets/railroadDiagram-O6MQD6OU-BDfEX1zC.js +1 -0
  176. synapto/web/assets/requirementDiagram-BXWQKSXE-0PWnZ_PF.js +84 -0
  177. synapto/web/assets/rough.esm-Dy-Kn_BL.js +1 -0
  178. synapto/web/assets/sankeyDiagram-P5KCCOFB-CzmXAlwy.js +40 -0
  179. synapto/web/assets/sequenceDiagram-WJ2MYXX4-C4kwKBBc.js +162 -0
  180. synapto/web/assets/sizeCapture-INFHLROL-3uHXrFqA.js +1 -0
  181. synapto/web/assets/src-DYcutCTp.js +1 -0
  182. synapto/web/assets/stateDiagram-D77RDMKH-DbpLbOeP.js +1 -0
  183. synapto/web/assets/stateDiagram-v2-MP3YSRHH-DNx3ipBZ.js +1 -0
  184. synapto/web/assets/swimlanes-42K2YHIH-DFi8XeS0.js +1 -0
  185. synapto/web/assets/swimlanesDiagram-VR7AAH4N-D1QzFjWS.js +8 -0
  186. synapto/web/assets/timeline-definition-24CTP7MA-CRE5CG6g.js +120 -0
  187. synapto/web/assets/treeView-Q6P3EWNA-DT2EnW9L.js +1 -0
  188. synapto/web/assets/treemap-WGGIJYW6-BCPoUUJE.js +1 -0
  189. synapto/web/assets/vennDiagram-4TSXK5OY-CE-jGbnB.js +34 -0
  190. synapto/web/assets/wardley-WFR3VGLG-CTplXEkW.js +1 -0
  191. synapto/web/assets/wardleyDiagram-VM6X3IG4-C_tavznA.js +78 -0
  192. synapto/web/assets/xychartDiagram-S5SC5T6Z-B4LGptT4.js +7 -0
  193. synapto/web/index.html +17 -0
  194. synapto/web/synapto-logo-lockup.png +0 -0
  195. synapto/web/synapto-mark.png +0 -0
  196. synapto_hub-0.1.0.dist-info/METADATA +125 -0
  197. synapto_hub-0.1.0.dist-info/RECORD +200 -0
  198. synapto_hub-0.1.0.dist-info/WHEEL +4 -0
  199. synapto_hub-0.1.0.dist-info/entry_points.txt +2 -0
  200. 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
@@ -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