synapto-hub 0.1.0__tar.gz

synapto_hub-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+
+# Built web UI (npm run build in web/)
+src/synapto/web/

synapto_hub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rick-scheper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synapto_hub-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: synapto-hub
+Version: 0.1.0
+Summary: Turn what your coding agent just built into an interactive lesson.
+Project-URL: Homepage, https://github.com/rick-scheper/synapto
+Project-URL: Issues, https://github.com/rick-scheper/synapto/issues
+Author: rick-scheper
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,coding-agents,jupyter,learning,lessons
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jupyter-client>=8.6
+Requires-Dist: nbformat>=5.10
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: websockets>=13
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rick-scheper/synapto/main/docs/design/design-system/assets/logos/synapto-logo-lockup.png" alt="Synapto" width="360">
+</p>
+
+**Understand the code your coding agent writes.**
+
+After Claude Code has built something, run `/debrief`. The agent writes a lesson about exactly what it just built and publishes it to Synapto, a learning hub that runs on your own machine. In the lesson you can:
+
+- **Explain:** read a walkthrough of the build, with diagrams.
+- **Decisions:** review the architectural choices the agent made, and the alternatives it rejected.
+- **Notebook:** run and edit the built code, split into functions. It runs in your project's own venv, on fixtures or on your real data.
+- **Quiz:** check that you understood it.
+- **Rebuild:** rewrite the key functions from a stub until the tests pass.
+
+<!-- Demo GIF: record docs/demo.gif (see "Recording the demo" below), then uncomment:
+<p align="center"><img src="https://raw.githubusercontent.com/rick-scheper/synapto/main/docs/demo.gif" alt="Running /debrief and opening the lesson" width="800"></p>
+-->
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/), Python ≥ 3.11 and [Claude Code](https://claude.com/claude-code).
+
+```sh
+uv tool install synapto-hub
+```
+
+This installs the `synapto` command. Next, add the Claude Code plugin, which provides the `/debrief` and `/decide` skills. Run these inside Claude Code:
+
+```
+/plugin marketplace add rick-scheper/synapto
+/plugin install synapto@synapto
+```
+
+Your project's venv needs `ipykernel` and `pytest`. `synapto doctor` checks for them and prints the install command if one is missing. The skill runs this check for you.
+
+## Use it
+
+1. In your project, let the agent build something.
+2. Type `/debrief`. The agent asks which parts you want: explanation, decisions, notebook, quiz and rebuild exercises. To skip that question, name them: `/debrief only explain,quiz`. To narrow the scope, use `/debrief since a1b2c3d` or `/debrief src/pkg/module.py`.
+3. The agent writes the lesson, checks it with `synapto validate` and publishes it with `synapto publish`. It then gives you the lesson URL.
+4. Start the hub with `synapto serve --open`. It serves on http://127.0.0.1:8765.
+
+### Before you build: `/decide`
+
+Facing a choice before any code exists, such as which database to use? Type `/decide "which database fits this project?"`, optionally followed by the candidates you have in mind. The agent researches the strongest candidates and publishes a **decision lesson**: an explanation of the problem space, the options compared on criteria that matter for your project, and a quiz.
+
+- `/decide guided "…"`: the lesson leads you to the agent's recommendation.
+- `/decide open "…"`: you make the call. Pick an option on the lesson's Options tab and write down why, then run `/decide review <lesson id>`. The agent challenges your reasoning in Claude Code, and the hub then shows its verdict next to the recommendation it wrote down *before* you chose. At the end it offers to record the decision as an ADR in your project.
+
+| Command | What it does |
+|---|---|
+| `synapto serve [--open] [--port N] [--reload]` | Start the hub on 127.0.0.1; `--reload` restarts a hub that's already running |
+| `synapto doctor [--python PATH]` | Check that a project interpreter can run lessons |
+| `synapto validate <bundle>` | Check a lesson bundle: it runs the notebook, and checks that the tests pass on the solution and fail on the stub |
+| `synapto publish <bundle> [--force]` | Validate a bundle and add it to your library |
+| `synapto decision show <id>` / `synapto decision verdict <id> <file>` | Read and store the review of an open decision (used by `/decide review`) |
+| `synapto remove <id> [--yes]` | Delete a lesson and your progress in it (or use **Delete lesson** in the hub) |
+
+Lessons and your progress live in `~/.synapto` (override with `SYNAPTO_HOME`).
+
+## Scope and safety
+
+Synapto v1 supports Python projects with Claude Code, for a single local user. Lesson code runs **with your own permissions** in your project's interpreter, with no sandbox. Lessons are generated from your own code. The server binds only to `127.0.0.1` and rejects cross-site and DNS-rebinding requests. See [spec §11](docs/spec.md#11-security-model).
+
+## Development
+
+```sh
+uv sync                                   # Python deps + dev tools
+uv run pytest
+claude --plugin-dir ./plugin              # run from a project to try the skill from this checkout
+uv tool install --editable .              # puts this checkout's `synapto` on PATH
+```
+
+The UI is a React + Vite app in `web/` ([ADR-0005](docs/adr/0005-frontend-react-vite.md)). Its design reference is in [docs/design/](docs/design/README.md). You only need Node to work on the UI:
+
+```sh
+cd web && npm install
+npm run build        # writes the app to src/synapto/web/, which `synapto serve` serves and the wheel ships
+npm run dev          # hot-reloading UI on :5173; proxies /api to a running `synapto serve`
+```
+
+[docs/spec.md](docs/spec.md) is the full specification, and [docs/adr/](docs/adr/README.md) holds the architecture decisions.
+
+### Releasing
+
+1. Bump `version` in `pyproject.toml`, `plugin/.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`.
+2. Tag and push: `git tag v0.1.0 && git push origin main v0.1.0`.
+
+The `release` workflow builds the UI, runs the tests and builds the wheel. It checks that the wheel contains the UI and that the tag matches the version, then publishes `synapto-hub` to PyPI through [trusted publishing](https://docs.pypi.org/trusted-publishers/). Set this up once on PyPI for the repo, the `release.yml` workflow and the `pypi` environment. The plugin goes live when its manifest reaches `main` on GitHub.
+
+### Recording the demo
+
+`docs/demo.gif` is about 20–30 s at 800 px wide. It shows: `/debrief` finishing in Claude Code with a `Lesson URL:` → the Library → Explain → running a Notebook cell → a passing Rebuild test run.
+
+## License
+
+[MIT](LICENSE)

synapto_hub-0.1.0/README.md

@@ -0,0 +1,97 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rick-scheper/synapto/main/docs/design/design-system/assets/logos/synapto-logo-lockup.png" alt="Synapto" width="360">
+</p>
+
+**Understand the code your coding agent writes.**
+
+After Claude Code has built something, run `/debrief`. The agent writes a lesson about exactly what it just built and publishes it to Synapto, a learning hub that runs on your own machine. In the lesson you can:
+
+- **Explain:** read a walkthrough of the build, with diagrams.
+- **Decisions:** review the architectural choices the agent made, and the alternatives it rejected.
+- **Notebook:** run and edit the built code, split into functions. It runs in your project's own venv, on fixtures or on your real data.
+- **Quiz:** check that you understood it.
+- **Rebuild:** rewrite the key functions from a stub until the tests pass.
+
+<!-- Demo GIF: record docs/demo.gif (see "Recording the demo" below), then uncomment:
+<p align="center"><img src="https://raw.githubusercontent.com/rick-scheper/synapto/main/docs/demo.gif" alt="Running /debrief and opening the lesson" width="800"></p>
+-->
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/), Python ≥ 3.11 and [Claude Code](https://claude.com/claude-code).
+
+```sh
+uv tool install synapto-hub
+```
+
+This installs the `synapto` command. Next, add the Claude Code plugin, which provides the `/debrief` and `/decide` skills. Run these inside Claude Code:
+
+```
+/plugin marketplace add rick-scheper/synapto
+/plugin install synapto@synapto
+```
+
+Your project's venv needs `ipykernel` and `pytest`. `synapto doctor` checks for them and prints the install command if one is missing. The skill runs this check for you.
+
+## Use it
+
+1. In your project, let the agent build something.
+2. Type `/debrief`. The agent asks which parts you want: explanation, decisions, notebook, quiz and rebuild exercises. To skip that question, name them: `/debrief only explain,quiz`. To narrow the scope, use `/debrief since a1b2c3d` or `/debrief src/pkg/module.py`.
+3. The agent writes the lesson, checks it with `synapto validate` and publishes it with `synapto publish`. It then gives you the lesson URL.
+4. Start the hub with `synapto serve --open`. It serves on http://127.0.0.1:8765.
+
+### Before you build: `/decide`
+
+Facing a choice before any code exists, such as which database to use? Type `/decide "which database fits this project?"`, optionally followed by the candidates you have in mind. The agent researches the strongest candidates and publishes a **decision lesson**: an explanation of the problem space, the options compared on criteria that matter for your project, and a quiz.
+
+- `/decide guided "…"`: the lesson leads you to the agent's recommendation.
+- `/decide open "…"`: you make the call. Pick an option on the lesson's Options tab and write down why, then run `/decide review <lesson id>`. The agent challenges your reasoning in Claude Code, and the hub then shows its verdict next to the recommendation it wrote down *before* you chose. At the end it offers to record the decision as an ADR in your project.
+
+| Command | What it does |
+|---|---|
+| `synapto serve [--open] [--port N] [--reload]` | Start the hub on 127.0.0.1; `--reload` restarts a hub that's already running |
+| `synapto doctor [--python PATH]` | Check that a project interpreter can run lessons |
+| `synapto validate <bundle>` | Check a lesson bundle: it runs the notebook, and checks that the tests pass on the solution and fail on the stub |
+| `synapto publish <bundle> [--force]` | Validate a bundle and add it to your library |
+| `synapto decision show <id>` / `synapto decision verdict <id> <file>` | Read and store the review of an open decision (used by `/decide review`) |
+| `synapto remove <id> [--yes]` | Delete a lesson and your progress in it (or use **Delete lesson** in the hub) |
+
+Lessons and your progress live in `~/.synapto` (override with `SYNAPTO_HOME`).
+
+## Scope and safety
+
+Synapto v1 supports Python projects with Claude Code, for a single local user. Lesson code runs **with your own permissions** in your project's interpreter, with no sandbox. Lessons are generated from your own code. The server binds only to `127.0.0.1` and rejects cross-site and DNS-rebinding requests. See [spec §11](docs/spec.md#11-security-model).
+
+## Development
+
+```sh
+uv sync                                   # Python deps + dev tools
+uv run pytest
+claude --plugin-dir ./plugin              # run from a project to try the skill from this checkout
+uv tool install --editable .              # puts this checkout's `synapto` on PATH
+```
+
+The UI is a React + Vite app in `web/` ([ADR-0005](docs/adr/0005-frontend-react-vite.md)). Its design reference is in [docs/design/](docs/design/README.md). You only need Node to work on the UI:
+
+```sh
+cd web && npm install
+npm run build        # writes the app to src/synapto/web/, which `synapto serve` serves and the wheel ships
+npm run dev          # hot-reloading UI on :5173; proxies /api to a running `synapto serve`
+```
+
+[docs/spec.md](docs/spec.md) is the full specification, and [docs/adr/](docs/adr/README.md) holds the architecture decisions.
+
+### Releasing
+
+1. Bump `version` in `pyproject.toml`, `plugin/.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`.
+2. Tag and push: `git tag v0.1.0 && git push origin main v0.1.0`.
+
+The `release` workflow builds the UI, runs the tests and builds the wheel. It checks that the wheel contains the UI and that the tag matches the version, then publishes `synapto-hub` to PyPI through [trusted publishing](https://docs.pypi.org/trusted-publishers/). Set this up once on PyPI for the repo, the `release.yml` workflow and the `pypi` environment. The plugin goes live when its manifest reaches `main` on GitHub.
+
+### Recording the demo
+
+`docs/demo.gif` is about 20–30 s at 800 px wide. It shows: `/debrief` finishing in Claude Code with a `Lesson URL:` → the Library → Explain → running a Notebook cell → a passing Rebuild test run.
+
+## License
+
+[MIT](LICENSE)

synapto_hub-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "synapto-hub"
+version = "0.1.0"
+description = "Turn what your coding agent just built into an interactive lesson."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "rick-scheper" }]
+keywords = ["claude-code", "coding-agents", "learning", "jupyter", "lessons"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Framework :: FastAPI",
+    "Framework :: Jupyter",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Education",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "fastapi>=0.115",
+    "jupyter_client>=8.6",
+    "nbformat>=5.10",
+    "pydantic>=2.7",
+    "typer>=0.12",
+    "uvicorn>=0.30",
+    # uvicorn needs it to serve the kernel WebSocket (spec §9.1).
+    "websockets>=13",
+]
+
+[project.urls]
+Homepage = "https://github.com/rick-scheper/synapto"
+Issues = "https://github.com/rick-scheper/synapto/issues"
+
+[project.scripts]
+synapto = "synapto.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    # The test suite uses the dev venv as the "project venv", so it needs
+    # what synapto doctor requires of a project interpreter.
+    "ipykernel>=6.29",
+    "httpx>=0.27",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/synapto", "/tests", "/README.md", "/LICENSE"]
+artifacts = ["/src/synapto/web/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/synapto"]
+# The built web UI is gitignored but ships in the wheel (ADR-0005).
+artifacts = ["/src/synapto/web/**"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = ["slow: creates a separate venv"]

synapto_hub-0.1.0/src/synapto/__init__.py

@@ -0,0 +1 @@
+"""Synapto: interactive lessons from what your coding agent just built."""

synapto_hub-0.1.0/src/synapto/bundle/__init__.py

@@ -0,0 +1 @@
+"""The lesson bundle: the contract between the /debrief skill and the hub (spec §5)."""

synapto_hub-0.1.0/src/synapto/bundle/decisions.py

@@ -0,0 +1,86 @@
+"""Parse ``decisions.md`` (spec §5.3) into one record per decision.
+
+The template is a ``## <title>`` section per decision with ``**Context:**``,
+``**Options:**``, ``**Chosen:**``, ``**Why:**``, ``**Trade-offs:**`` and
+``**ADR:**`` fields. The validator doesn't enforce it, so parsing is lenient:
+anything it can't place stays available as the section's raw Markdown, and a
+file without sections (the "no decisions were made" case) becomes a note.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel
+
+_SECTION = re.compile(r"^##[ \t]+(.+?)[ \t]*#*[ \t]*$", re.MULTILINE)
+_FIELD = re.compile(r"^\*\*(Context|Options|Chosen|Why|Trade-offs|ADR):?\*\*:?[ \t]*", re.MULTILINE | re.IGNORECASE)
+# "A — text", "(C — text)"; the dash may be an em dash, en dash or hyphen.
+_OPTION = re.compile(r"^\(?\s*([A-Za-z0-9]{1,3})\s*[—–-]\s*(.+?)\s*\)?\.?$", re.DOTALL)
+
+
+class DecisionOption(BaseModel):
+    id: str
+    label: str
+
+
+class Decision(BaseModel):
+    title: str
+    context: str | None = None
+    options: list[DecisionOption] = []
+    chosen: str | None = None
+    why: str | None = None
+    tradeoffs: str | None = None
+    adr: str | None = None
+    body: str
+    """The section's Markdown without its heading, for when the fields don't parse."""
+
+
+class Decisions(BaseModel):
+    decisions: list[Decision]
+    note: str | None = None
+    """Text before the first section, e.g. "No architectural decisions were made."."""
+
+
+def parse_decisions(text: str) -> Decisions:
+    sections = list(_SECTION.finditer(text))
+    intro = text[: sections[0].start()] if sections else text
+    intro = re.sub(r"^#[ \t].*$", "", intro, flags=re.MULTILINE).strip()  # drop a "# Decisions" title
+    decisions = []
+    for i, match in enumerate(sections):
+        end = sections[i + 1].start() if i + 1 < len(sections) else len(text)
+        decisions.append(_parse_section(match[1], text[match.end():end].strip()))
+    return Decisions(decisions=decisions, note=intro or None)
+
+
+def _parse_section(title: str, body: str) -> Decision:
+    fields: dict[str, str] = {}
+    marks = list(_FIELD.finditer(body))
+    for i, mark in enumerate(marks):
+        end = marks[i + 1].start() if i + 1 < len(marks) else len(body)
+        fields[mark[1].lower()] = " ".join(body[mark.end():end].split())
+
+    options = _parse_options(fields.get("options", ""))
+    chosen = fields.get("chosen")
+    if chosen and options:
+        # "B", "B — dict accumulation", "Option B"
+        ids = {o.id.lower(): o.id for o in options}
+        head = re.match(r"^(?:option\s+)?([A-Za-z0-9]{1,3})\b", chosen, re.IGNORECASE)
+        chosen = ids.get(head[1].lower()) if head else None
+    elif not options:
+        chosen = None
+
+    return Decision(
+        title=title, context=fields.get("context"), options=options, chosen=chosen,
+        why=fields.get("why"), tradeoffs=fields.get("trade-offs"), adr=fields.get("adr"), body=body,
+    )
+
+
+def _parse_options(text: str) -> list[DecisionOption]:
+    options = []
+    for part in (p.strip() for p in text.split(";")):
+        match = _OPTION.match(part)
+        if match is None:
+            return []  # one unrecognised part means the list isn't in the template's shape
+        options.append(DecisionOption(id=match[1], label=match[2]))
+    return options