Type Hints and Project Structure
Organise a growing AI codebase with clear modules, type hints and data models others can follow.
A taste of a lesson
If I type hint my function to return a Classification, is the model's JSON checked?
No. Type hints are notes for people and for static checkers; Python ignores them when the code runs. If the model returns JSON with a missing field or a label you did not expect, nothing stops it unless you check. So validate at the boundary: parse the JSON, confirm the required fields and allowed labels, either with a validation library or explicit checks, and only then build the Classification. What should happen in your app when the model returns an invalid label?
Written by the teacher as an example. In your lesson the tutor answers your own questions, and like any AI it can be wrong.
What you will be able to do
- Lay out a project with a source package, tests, configuration and prompt files
- Keep model calls behind one wrapper that is easy to fake in tests
- Add type hints with generics, optional values, literals and protocols
- Model JSON shaped data with dataclasses and typed dictionaries
- Validate external and model output at runtime where hints cannot help
Lesson plan
- 1 A layout that fits the project Choose a folder structure that matches your project's size and purpose. Start
- 2 Boundaries between modules Split responsibilities so model calls, data access and logic stay independent. Start
- 3 Type hints that earn their place Annotate function boundaries with clear, accurate hints. Start
- 4 Records and JSON shaped data Represent records with dataclasses and dict shaped data with TypedDict. Start
- 5 Static hints versus runtime validation Know where hints stop and runtime checks must start. Start
- 6 Restructure a real project Move an existing project into the new layout without breaking it. Start
Try asking
About this tutor
For developers whose AI project has grown from one notebook into several files that nobody is quite sure how to navigate. You learn to lay out a project (source package, tests, configuration, prompts as files), draw clean boundaries between data access, model calls and business logic, and add type hints that document intent and let a checker catch bugs before they run. The tutor covers dataclasses and typed dictionaries for JSON shaped data, optional values, literal choices, and the important difference between static hints and runtime validation of data coming from users or models.
Reviews
4.5
2 ratingsSample
- Hugo P.Sample
We moved my messy repo into a src layout over two sessions. Putting every model call behind one wrapper made testing possible. Some typing parts were dense but worth it.
- Nadia B.Sample
The point that hints do nothing at runtime was something I genuinely misunderstood. Validating model JSON at the boundary fixed a whole class of crashes.
About the teacher
Numerical Python and code quality for data and AI projects that have outgrown a single notebook
9 tutors 374 lessons taught Sample
I work on the part of AI projects nobody photographs: the arrays, dataframes, tests and packaging that let a prototype survive contact with real data. I came to this through scientific computing and later backend work, so I care about two things at once, getting the numbers right and keeping the code readable for the next person. My lessons are...
See Felix's profile and tutorsMore like this
Other tutors on the same or nearby topics.