Phase 7 — CLI & Concurrency

Chapters 65-67: From Library to Product

Your role: Tool Builder -- "I can build and ship production tools and async APIs"

SmartNotes has persistence, structure, and analytics. But it is still a library. The only way to use it is to write Python code: from smartnotes import .... Nobody wants to open a Python REPL to add a note. Phase 7 transforms SmartNotes from a library into a product: a command-line interface that anyone can run from a terminal, an async engine that handles multiple operations efficiently, and a web API that serves notes over HTTP.

By the end of Phase 7, SmartNotes is accessible three ways: from a terminal (smartnotes add "Python Tips" "My first note"), from a browser (localhost:8000/docs), and from any program that speaks HTTP. The TDG cycle you mastered in Phase 4 applies identically here. The specifications become CLI interfaces and API routes instead of function signatures. The tests verify commands and HTTP responses instead of return values.

#	Chapter	Lessons	Key Focus
65	Unix-Style CLI Tools	6	sys.argv, argparse, subcommands, exit codes, pipes, [project.scripts] entry point
66	Async Python	7	Blocking I/O, threading basics, async/await, asyncio.gather, async iteration, pytest-asyncio
67	FastAPI: Your First Web API	6	HTTP basics, FastAPI routes, Pydantic request/response, path/query params, TestClient, complete API

---

The SmartNotes Evolution

Each chapter adds a new way to interact with SmartNotes:

Chapter	SmartNotes evolution
Ch 65	SmartNotes becomes a CLI tool: smartnotes add, smartnotes search, smartnotes list, smartnotes export. Installable via [project.scripts] in pyproject.toml.
Ch 66	File export and import become async. async_export_all() writes concurrently using asyncio.gather(). Timing comparisons demonstrate the benefit.
Ch 67	SmartNotes gains a web API: GET/POST notes, search endpoint, export. Auto-documented at /docs. Tested with TestClient.

Deliverable: SmartNotes with a CLI interface, async file operations, and a FastAPI web API. All previous tests still passing. New tests verify CLI argument parsing, async operations, and API routes.

---

Starter Kit

Your PRIMM-AI+ starter kit from Chapter 42 works throughout Phase 7. The /predict, /investigate, /bug, /debug, and /tdg commands continue here. /tdg cycles now specify CLI interfaces and async functions instead of simple data-processing functions.

What You Need Before Starting

Phase 7 assumes you can:

• Drive the full TDG cycle independently (Ch 57)
• Design classes with __init__, methods, and properties (Ch 58-61)
• Read/write files across three formats: text, JSON, CSV (Ch 62)
• Organize code as a proper Python package with modules (Ch 63)
• Use comprehensions, generators, and functional tools (Ch 64)
• Validate external data with Pydantic BaseModel (Ch 55)

If any of these feel shaky, revisit the specific chapter before starting Phase 7.

This phase introduces external dependencies

Phases 1-6 used only the Python standard library plus Pydantic. Phase 7 adds fastapi, uvicorn, httpx, pytest-asyncio, and optionally aiofiles. Each new dependency is introduced in the lesson where it is first needed, with uv add commands and explanations of what the library provides.

Pacing and difficulty

Chapter 65 (CLI) and Chapter 67 (FastAPI) are practical and hands-on. Chapter 66 (Async Python) introduces a paradigm shift: functions that pause and resume. Lesson 3 of Chapter 66 ("Your First Coroutine") is the hardest lesson in this phase. If async def and await do not click immediately, that is normal. Re-read the forklift analogy, run the examples, and give yourself time. The TDG cycle you already know is your anchor.

Pacing: Plan 1.5-2 weeks for this phase. Chapter 65 (1-2 days), Chapter 66 (3-4 days, take extra time on Lesson 3), Chapter 67 (1-2 days).

Mid-Phase Checkpoint (After Chapter 65)

After completing Chapter 65, you should be able to:

• Create an argparse parser with positional and optional arguments
• Set up subcommands with add_subparsers and dispatch functions
• Use sys.exit() for exit codes and sys.stderr for error messages
• Read piped input from sys.stdin and detect interactive vs pipe mode
• Configure a [project.scripts] entry point and install with uv pip install -e .

If all five feel solid, you are ready for async (Ch 66). If any are shaky, revisit the specific lesson before continuing.

---

PRIMM-AI+ in This Phase

Stage	What You Do	Claude Code Tool
Predict [AI-FREE]	Predict CLI argument parsing behavior, async execution order, or API response format. Press Shift+Tab for Plan Mode.	Plan Mode protects prediction
Run	Press Shift+Tab to exit Plan Mode. Run CLI commands, async scripts, or API requests and compare to predictions.	You run it, not Claude Code
Investigate	Explore why argparse rejects an argument, why an async function did not run concurrently, or why an API returned 422. Use /investigate for Socratic questions.	/investigate probes mechanics
Modify	Add a new subcommand, convert a sync function to async, or add a new API route. Predict before running.	You edit, Claude Code reviews
Make [Mastery Gate]	Build a complete feature using /tdg: stub, tests, generate, verify, debug.	Your work, Claude Code guides

---

Phase 7 Complete: What You Can Do Now

By finishing Phase 7, you have:

• CLI mastery (Ch 65): You can build a command-line tool with argparse, subcommands, proper exit codes, stdin/stdout composability, and [project.scripts] entry points.
• Async fluency (Ch 66): You can write async functions, use asyncio.gather() for concurrent I/O, consume async generators, and test async code with pytest-asyncio.
• Web API basics (Ch 67): You can create FastAPI routes, use Pydantic models for request/response validation, and test APIs with TestClient.
• A real product (all three): SmartNotes is accessible from a terminal, a browser, and any HTTP client. It is no longer a Python package only developers can use.

In Phase 8, you automate verification. Right now, you run ruff check, pyright, and pytest manually. Phase 8 builds a GitHub Actions CI pipeline that runs your entire test suite on every commit. And it teaches you to audit AI-generated code for security vulnerabilities that AI consistently misses, because AI optimizes for functionality, not safety.