Pydantic Mastery

The problem — without Pydantic / সমস্যাটা — Pydantic ছাড়া

# Data comes from outside — you can't trust it
# ডেটা আসে বাইরে থেকে — বিশ্বাস করা যায় না
def create_user(data: dict):
    age = data["age"]      # might be "25" (a string!) / string হতে পারে!
    return age + 1        # 💥 CRASH — but much later, somewhere confusing

The solution — with Pydantic / সমাধান — Pydantic সহ

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

u = User(name="Rahim", age="25")   # "25" → 25 ✅ auto-converted / নিজেই convert
u = User(name="Rahim", age="abc")  # ❌ instant clear error / সাথে সাথে পরিষ্কার error

Where will you use it? / কোথায় কোথায় লাগবে?

from pydantic import BaseModel

class Student(BaseModel):
    id: int                    # required / আবশ্যক
    name: str                  # required / আবশ্যক
    is_active: bool = True     # optional (default True)
    bio: str | None = None     # optional, null চলবে

3 ways to create / তৈরির ৩টা উপায়

# 1) Directly / সরাসরি
s = Student(id=1, name="Karim")

# 2) From a dict (like parsed JSON) / dict থেকে
s = Student.model_validate({"id": 2, "name": "Fatima"})

# 3) From a raw JSON string / সরাসরি JSON string থেকে
s = Student.model_validate_json('{"id": 3, "name": "Ayan"}')

print(s.name)        # normal access / সাধারণভাবে ব্যবহার
print(s.is_active)   # True — default মান

Errors are your friend / Error আপনার বন্ধু

from pydantic import ValidationError

try:
    Student(id="abc", name=123)
except ValidationError as e:
    print(e)
# id   → Input should be a valid integer  [input_value='abc']
# ↑ WHICH field, WHAT problem, WHAT bad value — all at once!
# ↑ কোন field, কী সমস্যা, ভুল মান কী — সব একসাথে!

from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)                  # gt = greater than / এর বেশি
    rating: int = Field(default=5, ge=1, le=5) # 1 থেকে 5
    sku: str = Field(pattern=r"^[A-Z]{3}-\d{4}$") # e.g. ABC-1234

Free ready-made types / ফ্রি তৈরি-করা type

from pydantic import BaseModel, EmailStr, HttpUrl, SecretStr

class Account(BaseModel):
    email: EmailStr      # checks REAL email format / আসল email কিনা যাচাই
    website: HttpUrl     # must be a valid URL / বৈধ URL হতে হবে
    api_key: SecretStr   # hidden when printed! / print করলে লুকানো!

acc = Account(email="dev@x.com", website="https://x.com", api_key="sk-123")
print(acc.api_key)   # SecretStr('**********') 🔒 — safe in logs / log-এ নিরাপদ

class Address(BaseModel):
    city: str
    postal_code: str = Field(pattern=r"^\d{4}$")   # e.g. 1207

class Item(BaseModel):
    product: str
    quantity: int = Field(ge=1)

class Order(BaseModel):
    customer: str
    address: Address          # ← one model inside / ভেতরে একটা model
    items: list[Item]         # ← a LIST of models / model-এর list

order = Order.model_validate({
    "customer": "Nadia",
    "address": {"city": "Dhaka", "postal_code": "1207"},
    "items": [{"product": "Mouse", "quantity": 2}],
})
print(order.address.city)      # Dhaka
print(order.items[0].quantity) # 2

One field → @field_validator / এক field-এর জন্য

from pydantic import BaseModel, field_validator

class SignUp(BaseModel):
    username: str
    password: str

    @field_validator("username")
    @classmethod
    def no_spaces(cls, v):
        if " " in v:
            raise ValueError("No spaces allowed / স্পেস চলবে না")
        return v.lower()   # can also TRANSFORM! / বদলেও দিতে পারে!

u = SignUp(username="RAHIM", password="secret123")
print(u.username)   # "rahim" — lowercase হয়ে গেছে ✨

Multiple fields together → @model_validator / একাধিক field একসাথে

from datetime import date
from pydantic import BaseModel, model_validator

class Booking(BaseModel):
    check_in: date
    check_out: date

    @model_validator(mode="after")
    def dates_ok(self):
        if self.check_out <= self.check_in:
            raise ValueError("check_out must be after check_in / পরে হতে হবে")
        return self

Clean messy input first → mode="before" / আগে ময়লা পরিষ্কার

class Post(BaseModel):
    tags: list[str]

    @field_validator("tags", mode="before")
    @classmethod
    def split_string(cls, v):
        # Accept "a,b,c" OR ["a","b","c"] — both! / দুটোই নিন!
        if isinstance(v, str):
            return [t.strip() for t in v.split(",")]
        return v

Post(tags="ml, ai, backend").tags   # ['ml', 'ai', 'backend'] ✅

from datetime import datetime

class Event(BaseModel):
    name: str
    when: datetime

e = Event(name="Deploy", when="2026-07-03T10:30:00")

e.model_dump()        # {'name': 'Deploy', 'when': datetime(...)}  ← dict
e.model_dump_json()   # '{"name":"Deploy","when":"2026-07-03T10:30:00"}'
                      # datetime → ISO string automatically! / নিজে নিজেই!

# Control the output / output নিয়ন্ত্রণ:
e.model_dump(include={"name"})       # only these / শুধু এগুলো
e.model_dump(exclude_none=True)      # drop None fields / None বাদ
e.model_dump(exclude_unset=True)     # only fields user actually sent ⭐

The PATCH trick / PATCH-এর কৌশল

class UserUpdate(BaseModel):
    name: str | None = None
    email: str | None = None

@app.patch("/users/{user_id}")
def update_user(user_id: int, patch: UserUpdate):
    changes = patch.model_dump(exclude_unset=True)
    # User sent only {"name": "New"} → changes has ONLY name!
    # email untouched / email অক্ষত থাকল — এটাই আসল PATCH ✅
    db.update(user_id, **changes)

pip install pydantic-settings

from pydantic import Field, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env")

    app_name: str = "my-api"
    debug: bool = False
    database_url: str                          # required — no default!
    anthropic_api_key: SecretStr               # hidden in logs 🔒
    max_batch_size: int = Field(default=32, ge=1, le=256)

settings = Settings()   # reads env + .env, validates ALL / সব validate

# .env file / .env ফাইল
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
ANTHROPIC_API_KEY=sk-ant-xxxx
DEBUG=true
MAX_BATCH_SIZE=64

from fastapi import FastAPI
from pydantic import BaseModel, Field, EmailStr

app = FastAPI()

# INPUT model — has password / password আছে
class UserCreate(BaseModel):
    name: str = Field(min_length=1)
    email: EmailStr
    password: str = Field(min_length=8)

# OUTPUT model — NO password! / password নেই!
class UserOut(BaseModel):
    id: int
    name: str
    email: EmailStr

db = {}

@app.post("/users/", response_model=UserOut, status_code=201)
def create_user(user: UserCreate):
    new_id = len(db) + 1
    db[new_id] = {"id": new_id, **user.model_dump()}
    return db[new_id]
    # ↑ this dict HAS the password...
    # ...but response_model FILTERS it out! 🛡️
    # ↑ dict-এ password আছে... কিন্তু response_model ছেঁকে ফেলে দেয়!

Path + Query + Body together / তিনটা একসাথে

class ReviewIn(BaseModel):
    rating: int = Field(ge=1, le=5)
    comment: str = Field(max_length=500)

@app.post("/products/{product_id}/reviews")
def add_review(
    product_id: int,        # in the URL path → path param
    notify: bool = False,   # simple + not in path → query param
    review: ReviewIn = ..., # Pydantic model → request body
):
    return {"ok": True}

from enum import Enum
from pydantic import BaseModel, Field
import joblib

model = joblib.load("iris_model.pkl")

# INPUT — exactly what the model NEEDS / model-এর যা লাগবেই
class IrisFeatures(BaseModel):
    sepal_length: float = Field(gt=0, le=10)
    sepal_width:  float = Field(gt=0, le=10)
    petal_length: float = Field(gt=0, le=10)
    petal_width:  float = Field(gt=0, le=10)

    def to_vector(self):
        # GUARANTEED correct order / নিশ্চিত সঠিক ক্রম
        return [self.sepal_length, self.sepal_width,
                self.petal_length, self.petal_width]

# OUTPUT — typed prediction / typed prediction
class Prediction(BaseModel):
    species: str
    confidence: float = Field(ge=0, le=1)

@app.post("/predict", response_model=Prediction)
def predict(features: IrisFeatures):
    # Here, data is COMPLETE, TYPED, IN-RANGE — guaranteed ✅
    # এই লাইনে ডেটা সম্পূর্ণ, typed, সীমার মধ্যে — নিশ্চিত
    proba = model.predict_proba([features.to_vector()])[0]
    idx = proba.argmax()
    return Prediction(species=str(idx), confidence=round(float(proba[idx]), 4))

Batch prediction — protect your server / সার্ভার বাঁচান

class BatchRequest(BaseModel):
    rows: list[IrisFeatures] = Field(min_length=1, max_length=256)
    # max_length stops a 1-million-row request from killing your CPU!
    # max_length ১০ লাখ row-এর request থেকে CPU বাঁচায়!

from typing import Literal
from pydantic import BaseModel, Field

class Message(BaseModel):
    role: Literal["system", "user", "assistant"]  # ONLY these 3 / শুধু ৩টা
    content: str = Field(min_length=1, max_length=32_000)

class ChatRequest(BaseModel):
    messages: list[Message] = Field(min_length=1, max_length=100)
    temperature: float = Field(default=0.7, ge=0, le=2)
    max_tokens: int = Field(default=1024, ge=1, le=8192)

RAG query model / RAG-এর request model

class RAGQuery(BaseModel):
    question: str = Field(min_length=3, max_length=2000)
    top_k: int = Field(default=5, ge=1, le=20)      # how many chunks / কতগুলো
    collection: str = Field(pattern=r"^[a-z0-9_-]+$") # safe names only

import json, anthropic
from pydantic import BaseModel, Field, ValidationError

client = anthropic.Anthropic()

# STEP 1 — the shape you want / যে আকৃতি চান
class ResumeInfo(BaseModel):
    name: str
    years_experience: int = Field(ge=0, le=60)
    skills: list[str] = Field(min_length=1)
    seniority: str = Field(pattern=r"^(junior|mid|senior|lead)$")

def extract(text, retries=2):
    # STEP 2 — hand the schema to the LLM / LLM-কে schema দিন
    schema = json.dumps(ResumeInfo.model_json_schema())
    prompt = f"Extract as JSON matching this schema. JSON only.\n{schema}\n\n{text}"

    for _ in range(retries + 1):
        resp = client.messages.create(model="claude-sonnet-4-6",
                                       max_tokens=1000,
                                       messages=[{"role":"user","content":prompt}])
        raw = resp.content[0].text.strip()
        raw = raw.removeprefix("\`\`\`json").removesuffix("\`\`\`")
        try:
            # STEP 3 — validate / validate করুন
            return ResumeInfo.model_validate_json(raw)
        except ValidationError as e:
            # STEP 4 — retry WITH the error as the new prompt!
            # error-টাকেই নতুন prompt বানিয়ে আবার চেষ্টা!
            prompt = f"Your JSON had errors:\n{e}\nFix & return JSON only:\n{raw}"
    raise RuntimeError("LLM could not produce valid JSON / পারল না")

Tool / function calling / Tool calling

class WeatherQuery(BaseModel):
    """Get current weather for a city."""
    city: str = Field(description="City name, e.g. 'Dhaka'")
    unit: str = Field(default="celsius", pattern=r"^(celsius|fahrenheit)$")

# ONE model = docs + schema-for-LLM + validator-for-reply
# একটাই model = docs + LLM-এর schema + উত্তরের validator
tool = {
    "name": "get_weather",
    "description": WeatherQuery.__doc__,
    "input_schema": WeatherQuery.model_json_schema(),   # one line! ⚡
}

# When the LLM calls the tool, validate ITS arguments too:
def handle(args: dict):
    q = WeatherQuery.model_validate(args)   # LLM's args, checked! ✅
    return fetch_weather(q.city, q.unit)

1 · Enum & Literal — fixed choices / নির্দিষ্ট option

from enum import Enum

class Status(str, Enum):    # str + Enum → JSON-friendly
    pending = "pending"
    running = "running"
    done    = "done"

class Task(BaseModel):
    status: Status = Status.pending

Task(status="running")   # ✅
Task(status="paused")    # ❌ lists the 3 valid values / ৩টা বৈধ মান দেখায়

2 · Immutable (frozen) models / অপরিবর্তনীয় model

from pydantic import BaseModel, ConfigDict

class Config(BaseModel):
    model_config = ConfigDict(frozen=True)   # can't change after creation
    temperature: float

c = Config(temperature=0.7)
c.temperature = 1.5   # ❌ frozen! "who changed my settings?" bugs vanish
                    # "কে আমার settings বদলাল?" bug উধাও

3 · computed_field — auto-calculated output / হিসাব-করা মান

from pydantic import BaseModel, computed_field

class Usage(BaseModel):
    input_tokens: int
    output_tokens: int

    @computed_field
    @property
    def total(self) -> int:
        return self.input_tokens + self.output_tokens

Usage(input_tokens=1200, output_tokens=400).model_dump()
# {'input_tokens': 1200, 'output_tokens': 400, 'total': 1600}
# 'total' auto-appears in the JSON! / নিজে থেকেই JSON-এ যোগ হয়!

4 · TypeAdapter — validate without a class / class ছাড়াই যাচাই

from pydantic import TypeAdapter

# "Just check this is a list of floats" — no model needed
# "শুধু দেখো এটা float-এর list কিনা" — model লাগবে না
adapter = TypeAdapter(list[float])
embedding = adapter.validate_python([0.12, -0.5, 0.98])  # ✅ great for embeddings

7 golden rules / ৭টি সোনালি নিয়ম

Method cheat sheet / Method চিটশিট

When to use what / কখন কোনটা

🎯 Practice projects / অনুশীলন প্রজেক্ট

• User API — build UserCreate/UserOut; make sure password never appears in any response. — password যেন কোনো response-এ না থাকে।
• ML endpoint — wrap any sklearn model with Features + Prediction, batch capped at 100. — batch ১০০-তে সীমিত।
• LLM extractor — use the schema→validate→retry loop to pull structured data from messy text. — অগোছালো text থেকে structured ডেটা বের করুন।
• Config refactor — move every hardcoded value into a Settings class with a .env. — সব hardcoded মান .env-সহ Settings-এ সরান।