Skip to content

[Curriculum] Import path and package reality audit — make every code example runnable #8

Description

Problem

Every code example in the curriculum uses import paths and package names that do not exist in the current ecosystem. A student following the course cannot run a single example without encountering ImportError.

This breaks the core teaching loop: philosophy → example → run → understand. If the example can't run, the philosophy doesn't stick.

Phantom packages found

Phantom reference Where Learner impact
from qwed_sdk import QWEDLocal 52 occurrences across 18 files (Modules 0-13, CHEAT_SHEET, CONTRIBUTING) Most severe — the primary import path across the entire course. qwed_sdk was the old SDK package structure, not the current qwed-verification install. No examples work.
pip install qwed_finance Module 1, Module 8 Package does not exist on PyPI. Learner follows instructions and gets ERROR: No matching distribution found for qwed_finance
pip install qwed-legal README, Module 11 exercises Package does not exist. Learner cannot follow Module 11's "Deterministic AI Paralegal" exercises
pip install qwed_ucp Module 8 (commerce section) Package does not exist. The UCP commerce verification section is un-runnable
pip install qwed-mcp Module 1, Module 8 (Claude Desktop) Package does not exist. MCP integration section references it but cannot be tested
@qwed-ai/finance (npm) Module 8 (TypeScript SDK section) npm package does not exist

Dual-namespace confusion

Modules 12 and 13 use both qwed_sdk and qwed_new:

from qwed_sdk.guards import RAGGuard               # does not exist
from qwed_new.guards.process_guard import ProcessVerifier  # exists

This forces learners to understand two different package conventions simultaneously.

Scope

For each phantom reference, either:

  1. Make it real — Publish the package or create a mock/placeholder during the course
  2. Remove the reference — Rewrite the example to use only packages that actually exist
  3. Redirect — If the functionality lives inside qwed-verification core, update the import to point there

Specific decisions needed

Package Decision needed
qwed_sdkqwed_new or qwed-verification Does the core verification engine (qwed_new) expose everything the course needs? Or does the course need a separate SDK package?
qwed_finance Is this planned? Should the course reference it at all? Or rewrite examples using core qwed-verification math engine + manual ISOGuard logic?
qwed-legal Same question — planned package or curriculum-only concept? If not planned, Module 11 needs complete rewrite using core verification primitives
qwed_ucp Same question
qwed-mcp MCP server exists conceptually — should pip install qwed-mcp be made real, or should examples use local code?

Must change (unconditionally)

  • All 52 qwed_sdk references migrated to the real import path (whether that's qwed_new or a consolidated qwed-verification)
  • CHEAT_SHEET.md quick-start import updated
  • CONTRIBUTING.md example code updated
  • requirements.txt updated to match real package names

Acceptance criteria

  • Every code example in every module runs after pip install qwed-verification (or whatever the consolidated package is)
  • No import qwed_sdk remains anywhere in the repository
  • For each phantom package, a decision is documented (made real, removed, or redirected) — cross-reference in a decision log
  • Module 11 exercises are either updated to use real packages or removed
  • Module 8 UCP/Commerce section is either updated to use real packages or replaced
  • requirements.txt lists only real, installable packages

Non-goals

Why this is P1

Philosophically meaningless if the code doesn't run. A student can understand "Verified result state" perfectly but learn nothing if every import fails. This is the trust boundary between the curriculum and the student — if the code can't execute, the curriculum is not trustworthy.

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions