Define GenAI ADR Pydantic models with decision categories — lab audio overview

Host: Welcome back. You're in GenAI Architecture and Design Patterns — a course about the blueprints behind production AI systems. This chapter is called the GenAI ADR Engine. ADR stands for Architecture Decision Record — a short, dated document that captures a single important technical decision and the reasoning behind it. This chapter is about automating how teams capture those decisions for AI systems specifically. Today's skill: defining the shape of a decision record in code. Expert: Picture a mid-sized insurance company, maybe two hundred engineers, building out six AI features in parallel. One team picks a particular model for their claims assistant. Another team quietly picks a completely different one for document summarization. A third team is debating whether to fine-tune a model or use retrieval — that's the technique where instead of retraining the model, you let it look things up from a knowledge base at runtime. We sometimes call that RAG, Retrieval Augmented Generation. Six months later, nobody remembers why any of these choices were made. Costs are spiraling, two teams are paying for the same vendor twice, and a new hire asks "why aren't we using the cheaper option?" and nobody can answer. Compliance comes knocking and asks who approved what. Silence. That's the pain this chapter solves. A structured decision record is the cure — but only if it's machine-readable and enforced. Not a word processor document someone wrote once and forgot. So in this exercise, you're going to define the exact shape of a GenAI decision record so every team captures decisions the same way. Host: Since this is the first exercise in the chapter, this is your starting point — the groundwork the next two exercises build on. So what exactly will we build today? Expert: You'll build a structured data model — basically a strict template that says "every AI architecture decision in our company must have exactly these fields, filled in exactly these ways." You'll define what a decision looks like, what categories it can fall into, and what stages it can be in over its lifetime. For categories, think about the big GenAI choices: which model to use, where to host it — on your own hardware or through a cloud service — and whether to use retrieval or fine-tuning. Those are the three buckets you'll encode. For the lifecycle, every decision goes through stages. Someone proposes it. The team accepts it, or rejects it. Later, a better approach comes along and supersedes it — meaning the old decision is retired and replaced. You'll capture all of those stages so a decision's history is traceable. To make this real, you'll also build two small web endpoints — one to create a new decision record, and one to look up existing ones. For the heavy lifting, you'll use two Python libraries. The first is Pydantic, a tool that lets you define structured data with strict rules — if someone tries to create a record missing a required field, or puts a nonsense value in a field, Pydantic blocks it automatically. The second is FastAPI, a Python framework for building small web services quickly. The key idea — the "aha" — is this: decisions become valuable when they're structured data, not prose. Once a decision has fields a computer can read, you can query them, compare them, enforce policies on them, and wire them into dashboards. That's the foundation. Host: Got it. Before we start — what's the one thing that trips people up on this kind of exercise? Expert: The biggest trap is making the model too loose. Beginners tend to use free-form text fields for everything — category is just a string, status is just a string, the rationale is a giant blob. That feels easier in the moment, but it destroys the whole point. If category is free text, one team writes "model choice," another writes "model selection," a third writes "LLM pick" — and now you can't filter or report across them. The company still has the same sprawling mess, just stored in a different place. So before you start, lean hard into strict, fixed lists of allowed values. For category, only the three options we discussed. For status, only the handful of lifecycle stages. When you find yourself reaching for an open text field, pause and ask — could this be a fixed list instead? If yes, make it one. The rigor you enforce here pays off for the rest of the chapter, because the next two exercises assume this structure is tight. Host: Perfect. So by the end of this exercise, what will the listener walk away being able to do? Expert: After this, you'll be able to take any architecture decision your team makes — model choice, hosting strategy, retrieval versus fine-tuning — and capture it as a structured, validated, queryable record through a simple web service. You'll have the backbone of a decision registry your team can build real governance on top of. This is the kind of building block an architecture group can bring straight into their next review cycle — a foundation for making AI decisions traceable across the whole organization. Next, you'll extend this foundation by adding scoring. Right now, a decision just says "we picked option A." In the next exercise, you'll build the part that compares options side by side — weighing each one against criteria like cost, latency, and accuracy, and ranking them automatically. Thanks for listening, and good luck.