Chapter 49: Functions as Contracts
In Chapter 46, you completed your first TDG cycle with a simple function: one parameter, one return type. In Chapters 47 and 48, you built the type vocabulary: int, float, str, bool, None, list[str], dict[str, int]. Now you combine them.
A function signature is a contract. It says: "Give me these inputs, in these types, and I will give you back this output, in this type." When you write:
def search_notes(notes: list[str], query: str, case_sensitive: bool = False) -> list[str]:
...
You are not writing code. You are writing a specification. This one line tells AI (and pyright, and every developer who reads it) exactly what the function needs, what it returns, and what the default behavior is. AI reads this and knows what to build. Pyright reads this and knows what to check.
This chapter teaches you to write these specifications: multiple parameters so functions can take more than one input, return types so the output is guaranteed, default values so callers can skip common arguments, keyword arguments so calls are readable, and docstrings so humans understand the intent. By the end, you will write complete SmartNotes function specifications and let AI generate every implementation.
Chapter Lessons
| Lesson | Title | What You Do | Duration |
|---|---|---|---|
| 1 | Parameters and Return Types | Write multi-parameter signatures, understand return vs print | 25 min |
| 2 | Default Values and Keyword Arguments | Add defaults, call with keyword args | 20 min |
| 3 | Docstrings: The Human-Readable Spec | Write docstrings that describe what, not how | 15 min |
| 4 | Writing Real Specifications | Full TDG cycle with SmartNotes stubs, tests, and AI-generated bodies | 25 min |
PRIMM-AI+ in This Chapter
Every lesson includes a PRIMM-AI+ Practice section. You are now writing function signatures, so predictions involve parameter types, return types, and what happens when you call a function with different arguments.
| Stage | What You Do | Claude Code Tool |
|---|---|---|
| Predict [AI-FREE] | Predict what a function returns for given arguments, or what pyright flags for a wrong type. Press Shift+Tab for Plan Mode. | Plan Mode protects prediction |
| Run | Press Shift+Tab to exit Plan Mode. Execute the code, compare to your prediction. | You run it, not Claude Code |
| Investigate | Write one sentence explaining why your prediction was right or wrong. Use /investigate for Socratic questions. | /investigate probes mechanics |
| Modify | Change a parameter type or default value and predict the new result | You edit, Claude Code reviews |
| Make [Mastery Gate] | Write a function signature from scratch given a plain-English description. Use /tdg for TDG cycles (Lesson 4). | Your work, Claude Code generates |
If you installed the PRIMM-AI+ starter kit in Chapter 42, your /predict, /investigate, and /bug commands still work. This chapter also uses /tdg for TDG cycles in Lesson 4. If you don't have it, update your kit from panaversity/primm-ai-starter-kit.
The SmartNotes Connection
At the end of this chapter, you will write SmartNotes function stubs including word_count(), format_title(), note_preview(), create_note(), and merge_metadata(), all with typed parameters, return types, and docstrings. Then you will write tests, let AI generate every implementation, and verify with pytest and pyright. These are the first real SmartNotes functions, and you will build on them throughout the rest of the course.