Python Nexus tutorial: planning drafts by nadvolod · Pull Request #7 · temporalio/edu-nexus-code

nadvolod · 2026-05-29T16:32:15Z

What this is

Planning artifacts for the Python port of the Java Decoupling Temporal Services with Nexus tutorial. Not the code itself — three review-ready docs that lock the tutorial structure, sandbox layout, and pacing before anyone writes Python.

All three live in python/_planning/ so they're easy to delete (or relocate) once the actual python/ code lands in a follow-up PR.

Files

TUTORIAL.md — Full draft of the learner-facing tutorial. 11 modules, ~32 min for the Instruqt path. Mirrors the Java arc monolith → decoupled → durability proven, but cuts the human-in-the-loop path to fit the time budget (signposted in Going further). 2  placeholders inline with descriptions of what each should depict.
SANDBOX.md — Spec for the future python/ code folder: directory layout, solution branches (solution/todo-1 … solution/complete), devcontainer (local-only), and Instruqt step-to-module mapping with per-step auto-checks.
AUDIT.md — Pacing audit (66% active, clears the 60% target), terminology audit, completeness check against the 6 learning outcomes, and open questions to resolve before publishing.

Pedagogical flow: "do first, understand second"

The first three modules implement the edu-skill's core principle — give learners running code, let them find the problems, then explain:

Module 1 — Run the monolith. Hands-on first contact with the codebase. Three transactions, all in one Namespace, on one Task Queue, in one Worker.
Module 2 — What's wrong with this picture? A Socratic prompt asks the learner to spot the problems before reading the answer. Reveal (<details> block) lists three concrete failure modes — shared blast radius, shared deploy cadence, shared scaling — plus the three-alternatives comparison that motivates Nexus.
Module 3 — Nexus building blocks. Just-in-time terminology, immediately before the first TODO.

Modules 4–9 are the guided transformation (5 TODOs, 2 checkpoints, the kill-the-worker durability demo). Module 10 wraps up with the Nexus vs. Child Workflow vs. Activity decision rule as a 3-bullet callout, closing the loop back to the problems surfaced in Module 2.

Feedback-driven decisions vs. straight Java port

Informed by Replay 2026 workshop feedback (5 sessions / 97 responses, including the "Nexus Morning Session – Python"):

Instruqt-first setup. Module 0 is Instruqt-only (~2 min). Local setup lives in a clearly-marked appendix at the end and is not counted in the 30-min budget. Addresses the most-cited workshop issue (WiFi, Docker rate limits, corporate laptops, API keys).
Cut scope to fit time. The 75-min original draft was trimmed to ~32 min by removing the human-review path (sync Nexus operation + Workflow Update) and the full quiz/scenario module. Both are signposted in Going further for a possible Part 2.
Decision rule preserved. The Nexus vs. Child Workflow guidance — the most-requested Nexus content from workshop attendees — survives as a 3-bullet callout in the Module 10 wrap-up.

Python-specific structural difference from Java

The Python SDK puts the Nexus endpoint binding inside the Workflow via workflow.create_nexus_client(endpoint=...) — no NexusServiceOptions at Worker registration like Java. One less concept for learners to track. Module 7 (TODO 4 — stub swap) highlights this.

What I'm looking for from reviewers

Voice/format check against the existing Java tutorial on learn.temporal.io — is the prose at the right level?
Python Nexus API accuracy — code blocks should run as-is on temporalio>=1.14.1. AUDIT.md flags this as open question Add Java decouple-monolith Nexus exercise #1.
Module 2 Socratic prompt + reveal — does the discovery moment land, or do learners need more scaffolding before the reflection?
Module 10 decision callout — is the 3-bullet version enough, or does it need to be expanded into a fuller decision guide?
Pacing realism for the 30-min Instruqt path.

Not in this PR

Python code under python/{shared,compliance,payments,monolith}/ — next PR, once this plan is locked.
Diagrams — 2 placeholders only; the user noted they want to "improve on some diagrams" in production.

Source

Designed using the temporal-edu-skills /edu:learning-experience-designer skill.

🤖 Generated with Claude Code

Mirrors the Java decouple-monolith tutorial with Python-idiomatic code. - TUTORIAL.md — Mode A draft, 14 modules, ~75 min, monolith→decoupled→durability arc - SANDBOX.md — repo structure for python/ folder, Instruqt step mapping, test strategy - AUDIT.md — pacing audit (73% active), terminology check, completeness vs. learning outcomes Feedback-driven additions vs. straight Java port: - "Why Nexus vs alternatives" framing in Module 1 - Nexus vs. Child Workflow decision guide in Module 12 - Local-fallback setup alongside Instruqt in Module 0 Designed using the temporal-edu-skills /edu:learning-experience-designer skill, informed by Replay 2026 workshop feedback (5 sessions, 97 responses). Diagrams marked inline as  placeholders for later production. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds draft planning documentation for a Python port of the “Decoupling Temporal Services with Nexus” tutorial, intended to lock tutorial structure, sandbox layout, and pacing before the Python code/exercises are implemented.

Changes:

Adds a full learner-facing tutorial draft with module structure, checkpoints, and diagram placeholders.
Specifies the intended /python sandbox folder layout, solution branch strategy, and Instruqt step mapping.
Provides a pacing/terminology/completeness audit plus open technical questions to confirm before publishing.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
python/_planning/TUTORIAL.md	Draft end-to-end tutorial narrative + code snippets + checkpoints/quiz/decision guide
python/_planning/SANDBOX.md	Proposed Python sandbox structure, solution branches, devcontainer spec, and Instruqt mapping
python/_planning/AUDIT.md	Pacing + terminology audit, learning-outcome coverage, and pre-publish open questions

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

nadvolod · 2026-05-29T18:21:20Z

+# payments/review_caller.py — for reference, no edits required
+from temporalio import workflow
+


Resolved in 5bf1a56 — the entire human-review path (including payments/review_caller.py) was cut to fit the 30-min budget, so the unimported-timedelta snippet is gone with it. The sync-operation pattern is signposted in Going further if a Part 2 picks it up.

nadvolod · 2026-05-29T18:01:20Z

+## Test strategy
+
+Per `AGENTS.md` non-negotiable #6 (majority integration tests on real DB/API, minority unit, plus E2E):
+


Agreed and remove the testing section as this isn't relevant in this workshop

Removed the testing section from python/_planning/SANDBOX.md as requested in commit ab0a2af.

+| E2E              | `test_e2e_nexus.py`                   | Full dev server, both namespaces, real endpoint, three transactions    |
+| E2E (manual)     | "kill-the-worker" script in `tests/manual/` | Helper that scripts the Module 10 outage demo for CI verification        |
+
+All tests must **fail loudly** if a required env var is unset — never skip. (AGENTS.md non-negotiable #10.)


nadvolod · 2026-05-29T18:21:22Z

+
+## Terminology audit
+
+Cross-referenced against `_shared/terminology.md`.


Fixed in 5bf1a56. The reference now reads 'Cross-referenced against Temporal terminology guidance (e.g., the disambiguation rules tracked by the Temporal Edu team)' — pointing at the team-owned source rather than a file path that doesn't live in this repo.

nadvolod · 2026-05-29T18:21:17Z

+2. **Check compliance** (risk score, sanctions screening).
+3. **Execute** the payment through the gateway.
+
+All three steps live in a single Worker, in a single Namespace, on a single Task Queue. The Payments team and the Compliance team share the deployment. That means **one team's bug is everyone's outage** — a NullPointerException in compliance code crashes the Worker mid-payment, and now nobody can process money.


Fixed in 5bf1a56. The Module 1 framing now says 'a runtime crash in compliance code kills the Worker mid-payment' — language-neutral.

CLAassistant · 2026-05-29T18:05:30Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ nadvolod
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

nadvolod · 2026-05-29T18:06:55Z

+
+Skip to Module 1.
+
+### Option 2 — Local fallback


Local fallback should be a section at the end. We can link to it here but we should recommend Instruqt as it will allow the user to get up and running quickly with no environmental issues. If they really want, they can run locally, but that will be a separate section at the end to not distract from a good flow

Updated in 43c65b7: Module 0 now recommends Instruqt first and links local setup to a separate end section (Appendix A — Local fallback setup).

Done in 5bf1a56. Module 0 is now Instruqt-only (~2 min) with a one-line pointer to the appendix. The full local setup steps live in Appendix — Local setup (optional) at the end, clearly marked as not counting toward the 30-min budget.

nadvolod · 2026-05-29T18:10:36Z

@@ -0,0 +1,864 @@
+# Decoupling Temporal Services with Nexus and the Python SDK
+
+**Time:** ~75 min · **Difficulty:** Intermediate · **SDK:** Python 3.10+


@copilot 75 minutes is a long time! Can we limit it to 30? I don't think the Java tutorial takes 75 min

Updated in 43c65b7: tutorial timing is now ~30 min (core path), with AUDIT aligned to a 30-minute core path and extended content clearly marked as optional.

Done in 5bf1a56 — this goes further than the relabel-only patch in 43c65b7 by actually cutting Modules 11 (human review path) and 12 (full quiz/decision guide) and compressing the remaining modules. New total: ~33 min for the Instruqt core path (the 30-min budget excludes the local-setup appendix per your follow-up note). The Nexus-vs-Child-Workflow decision rule survives as a 3-bullet callout in the Module 10 wrap-up.

Resolves PR #7 review comments. Tutorial scope cuts to fit 30 min (Instruqt path only — local appendix excluded): - Drop Module 11 (Human review path / sync Nexus operation + Workflow Update) - Drop Module 12 (Quiz + scenario questions); decision rule survives as a 3-bullet callout in the wrap-up - Compress remaining modules from ~75 min total → ~33 min total Structure changes: - Module 0 is now Instruqt-only (~2 min); local setup moved to a clearly-marked appendix at the end with a note that its time is NOT counted toward the budget - Tutorial now has 11 modules (was 14) Copilot inline-comment fixes: - Remove Java-ism "NullPointerException" from Module 1 framing (was a leftover from the Java port) - Reference to payments/review_caller.py (which had a missing timedelta import) is gone with the rest of the human-review path - Remove _shared/terminology.md reference in AUDIT.md; replace with a generic pointer to Temporal Edu terminology guidance Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Per PR review feedback: better pedagogy to run the monolith first, then let learners discover the problems themselves via a Socratic prompt, then introduce Nexus terminology just-in-time before the transformation. Module order changes: Before After 1. The problem (read) 1. Run the monolith (do) 2. Nexus building blocks (read) 2. What's wrong with this picture? (reflect + reveal) 3. Run the monolith (do) 3. Nexus building blocks (read) Module 2 is a new Socratic discovery step: - Three concrete observations from the running system (one Namespace, one Task Queue, one Worker) - A 30-second reflection prompt: "what goes wrong?" - A <details> reveal with three concrete failure modes (blast radius, deploy cadence, scaling) and the three-alternatives comparison table that was previously the body of old Module 1 - Module 10 wrap-up callback now references "the three problems from Module 2" to close the loop Aligns with the edu skill's "Do, then understand" core principle and the workshop-feedback request to favor hands-on time. New active ratio is 66% (up from 61%); total stays ~32 min. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

nadvolod · 2026-05-29T18:41:20Z

Reordered modules 1-3 in 439f726 per the "do-first, understand-second" feedback. Diff:

Before	After
1. The problem (read)	1. Run the monolith (do)
2. Nexus building blocks (read)	2. What's wrong with this picture? (reflect)
3. Run the monolith (do)	3. Nexus building blocks (read, just-in-time)

New Module 2 — What's wrong with this picture? has three pieces:

Three concrete observations from the running system (one Namespace, one Task Queue, one Worker)
A 30-second reflection prompt
A <details> reveal with three failure modes (shared blast radius / deploy cadence / scaling) and the three-alternatives comparison table that was previously upfront

Module 10 wrap-up now closes the loop with "Remember the three problems from Module 2..."

Pacing impact: active ratio 61% → 66% (more time hands-on). Total stays ~32 min.

nadvolod · 2026-05-31T20:07:18Z

+
+## Prerequisites
+
+- Comfortable with Temporal **Workflows**, **Activities**, and **Workers** in Python. If not, run the [Hello World tutorial](https://learn.temporal.io/getting_started/python/hello_world_in_python/) first.


Is this tutorial up to date? should we point elsewhere?

…lone Activities Per PR review feedback. - Module 3 mental model: replace the mixed-metaphor "interface / method / address-book entry" line with a single coherent HTTP+DNS analogy, plus an explicit team-ownership paragraph (who owns the implementation vs. the call site) - Module 9 opener: drop "This is the demo that sells Nexus" — was selling to the learner instead of teaching. Replaced with "Now we prove the durability claim" - Module 10 decision guide: add a fourth bullet for Standalone Activities (Pre-release Python feature for starting Activities directly from a Client without a wrapping Workflow). Updated the one-line heuristic accordingly - Module 10 "Going further": added Standalone Activities link as the first follow-on topic Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…d Standalone Activities" This reverts commit 681fc14.

nadvolod marked this pull request as ready for review May 29, 2026 17:50

Copilot AI review requested due to automatic review settings May 29, 2026 17:50

Copilot started reviewing on behalf of nadvolod May 29, 2026 17:50 View session

Copilot AI reviewed May 29, 2026

View reviewed changes

Copilot started work on behalf of nadvolod May 29, 2026 18:01 View session

docs(python): remove SANDBOX testing strategy section

ab0a2af

Copilot finished work on behalf of nadvolod May 29, 2026 18:06

nadvolod commented May 29, 2026

View reviewed changes

Copilot started work on behalf of nadvolod May 29, 2026 18:11 View session

docs(python): prioritize Instruqt flow and set 30-min core path

43c65b7

Copilot finished work on behalf of nadvolod May 29, 2026 18:16

nadvolod and others added 2 commits May 29, 2026 14:20

nadvolod commented May 31, 2026

View reviewed changes

nadvolod and others added 2 commits June 3, 2026 08:30

Revert "docs(python): drop sales-y phrasing, rewrite mental model, ad…

e92df8b

…d Standalone Activities" This reverts commit 681fc14.

		# payments/review_caller.py — for reference, no edits required
		from temporalio import workflow

		## Test strategy

		Per `AGENTS.md` non-negotiable #6 (majority integration tests on real DB/API, minority unit, plus E2E):


		## Terminology audit

		Cross-referenced against `_shared/terminology.md`.

		@@ -0,0 +1,864 @@
		# Decoupling Temporal Services with Nexus and the Python SDK

		Time: ~75 min · Difficulty: Intermediate · SDK: Python 3.10+


		## Prerequisites

		- Comfortable with Temporal Workflows, Activities, and Workers in Python. If not, run the [Hello World tutorial](https://learn.temporal.io/getting_started/python/hello_world_in_python/) first.

Uh oh!

Conversation

nadvolod commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this is

Files

Pedagogical flow: "do first, understand second"

Feedback-driven decisions vs. straight Java port

Python-specific structural difference from Java

What I'm looking for from reviewers

Not in this PR

Source

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CLAassistant commented May 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nadvolod commented May 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nadvolod commented May 29, 2026 •

edited

Loading