Pydantic মডেল, ভ্যালিডেশন ও এরর রেসপন্স

mkdir -p ~/projects
cd ~/projects
uv init -q --no-package bitbyte-prompts
cd bitbyte-prompts
uv add -q "fastapi[standard]"
rm main.py
mkdir app
touch app/__init__.py
ls -A app

__init__.py

# file: app/schemas.py
"""The shapes of the data the prompt library accepts and returns."""
from typing import Annotated, Literal

from pydantic import BaseModel, EmailStr, Field, field_validator


class PromptBase(BaseModel):
    name: Annotated[str, Field(min_length=3, max_length=40, pattern=r"^[a-z0-9-]+$")]
    template: Annotated[str, Field(min_length=10, max_length=2000)]
    model: Literal["bitbyte-mini", "bitbyte-pro"] = "bitbyte-mini"
    temperature: Annotated[float, Field(ge=0, le=2)] = 0.7
    tags: Annotated[list[str], Field(max_length=5)] = []

    @field_validator("template")
    @classmethod
    def must_have_question(cls, value: str) -> str:
        if "{question}" not in value:
            raise ValueError("template must contain the {question} placeholder")
        return value


class PromptCreate(PromptBase):
    """What a client sends to create a prompt."""
    owner_email: EmailStr


class PromptPublic(PromptBase):
    """What the API returns: no owner_email."""
    id: int


class RenderRequest(BaseModel):
    question: Annotated[str, Field(min_length=1, max_length=500)]


class RenderResponse(BaseModel):
    prompt_id: int
    model: str
    temperature: float
    text: str

from app.schemas import PromptCreate, PromptPublic

prompt = PromptCreate(
    name="course-helper",
    template="You are a friendly tutor. Answer briefly: {question}",
    temperature="0.2",
    owner_email="nadia@example.com",
)
print(repr(prompt.temperature), prompt.model, prompt.tags)
print(prompt.model_dump())
print(prompt.model_dump_json(exclude={"owner_email"}))

0.2 bitbyte-mini []
{'name': 'course-helper', 'template': 'You are a friendly tutor. Answer briefly: {question}', 'model': 'bitbyte-mini', 'temperature': 0.2, 'tags': [], 'owner_email': 'nadia@example.com'}
{"name":"course-helper","template":"You are a friendly tutor. Answer briefly: {question}","model":"bitbyte-mini","temperature":0.2,"tags":[]}

from pydantic import ValidationError

try:
    PromptCreate(
        name="Course Helper!",
        template="Answer this.",
        model="gpt-x",
        temperature=3,
        owner_email="nadia-at-example",
    )
except ValidationError as exc:
    print(exc.error_count(), "errors")
    for error in exc.errors():
        print(error["loc"], "|", error["type"], "|", error["msg"])

5 errors
('name',) | string_pattern_mismatch | String should match pattern '^[a-z0-9-]+$'
('template',) | value_error | Value error, template must contain the {question} placeholder
('model',) | literal_error | Input should be 'bitbyte-mini' or 'bitbyte-pro'
('temperature',) | less_than_equal | Input should be less than or equal to 2
('owner_email',) | value_error | value is not a valid email address: An email address must have an @-sign.

# file: app/main.py
"""BitByte Prompt Library: store prompt templates and fill them in."""
from itertools import count
from typing import Annotated

from fastapi import FastAPI, HTTPException, Path, status

from app.schemas import PromptCreate, PromptPublic, RenderRequest, RenderResponse

app = FastAPI(title="BitByte Prompt Library", version="0.1.0")

PROMPTS: dict[int, dict] = {}   # id -> সংরক্ষিত রেকর্ড (owner_email সহ)
_next_id = count(1)

PromptId = Annotated[int, Path(ge=1, description="The prompt's id")]


def find_prompt(prompt_id: int) -> dict:
    record = PROMPTS.get(prompt_id)
    if record is None:
        raise HTTPException(status_code=404, detail=f"Prompt {prompt_id} not found")
    return record


@app.get("/health")
def health():
    return {"status": "ok"}


@app.post("/prompts", status_code=status.HTTP_201_CREATED)
def create_prompt(prompt: PromptCreate) -> PromptPublic:
    if any(p["name"] == prompt.name for p in PROMPTS.values()):
        raise HTTPException(status_code=409, detail=f"A prompt named {prompt.name!r} already exists")
    record = {"id": next(_next_id), **prompt.model_dump()}
    PROMPTS[record["id"]] = record
    return record


@app.get("/prompts")
def list_prompts(tag: str | None = None) -> list[PromptPublic]:
    return [p for p in PROMPTS.values() if tag is None or tag in p["tags"]]


@app.get("/prompts/{prompt_id}")
def get_prompt(prompt_id: PromptId) -> PromptPublic:
    return find_prompt(prompt_id)


@app.delete("/prompts/{prompt_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_prompt(prompt_id: PromptId) -> None:
    find_prompt(prompt_id)
    del PROMPTS[prompt_id]


@app.post("/prompts/{prompt_id}/render")
def render_prompt(prompt_id: PromptId, body: RenderRequest) -> RenderResponse:
    record = find_prompt(prompt_id)
    return RenderResponse(
        prompt_id=prompt_id,
        model=record["model"],
        temperature=record["temperature"],
        text=record["template"].replace("{question}", body.question),
    )

uv run fastapi run app/main.py --port 8000 > server.log 2>&1 &
curl -s --retry 20 --retry-connrefused --retry-delay 0 http://localhost:8000/health

{"status":"ok"}

curl -s -w "\nstatus: %{http_code}\n" -X POST http://localhost:8000/prompts \
  -H "Content-Type: application/json" \
  -d '{"name": "course-helper",
       "template": "You are a friendly tutor. Answer briefly: {question}",
       "tags": ["tutor", "short"],
       "owner_email": "nadia@example.com"}'

{"name":"course-helper","template":"You are a friendly tutor. Answer briefly: {question}","model":"bitbyte-mini","temperature":0.7,"tags":["tutor","short"],"id":1}
status: 201

curl -s -X POST http://localhost:8000/prompts -H "Content-Type: application/json" \
  -d '{"name": "bangla-summary", "template": "Summarise in simple Bangla: {question}",
       "model": "bitbyte-pro", "temperature": 0.3, "tags": ["summary"], "owner_email": "rafi@example.com"}'
echo
curl -s "http://localhost:8000/prompts?tag=tutor"
echo
curl -s http://localhost:8000/prompts/2

{"name":"bangla-summary","template":"Summarise in simple Bangla: {question}","model":"bitbyte-pro","temperature":0.3,"tags":["summary"],"id":2}
[{"name":"course-helper","template":"You are a friendly tutor. Answer briefly: {question}","model":"bitbyte-mini","temperature":0.7,"tags":["tutor","short"],"id":1}]
{"name":"bangla-summary","template":"Summarise in simple Bangla: {question}","model":"bitbyte-pro","temperature":0.3,"tags":["summary"],"id":2}

curl -s -X POST http://localhost:8000/prompts -H "Content-Type: application/json" \
  -d '{"name": "Course Helper!", "template": "Answer this.", "temperature": 3, "owner_email": "nadia@example.com"}' \
  | python -m json.tool

{
    "detail": [
        {
            "type": "string_pattern_mismatch",
            "loc": [
                "body",
                "name"
            ],
            "msg": "String should match pattern '^[a-z0-9-]+$'",
            "input": "Course Helper!",
            "ctx": {
                "pattern": "^[a-z0-9-]+$"
            }
        },
        {
            "type": "value_error",
            "loc": [
                "body",
                "template"
            ],
            "msg": "Value error, template must contain the {question} placeholder",
            "input": "Answer this.",
            "ctx": {
                "error": {}
            }
        },
        {
            "type": "less_than_equal",
            "loc": [
                "body",
                "temperature"
            ],
            "msg": "Input should be less than or equal to 2",
            "input": 3,
            "ctx": {
                "le": 2.0
            }
        }
    ]
}

curl -s -X POST http://localhost:8000/prompts -H "Content-Type: application/json" \
  -d '{"name": "broken", "template": "Answer: {question}", "owner_email": "x@example.com",' \
  | python -m json.tool
curl -s -X POST http://localhost:8000/prompts -H "Content-Type: application/json" \
  -d '{"name": "too-many-tags", "template": "Answer: {question}", "owner_email": "x@example.com",
       "tags": ["a", "b", "c", "d", "e", "f"]}' \
  | python -m json.tool

{
    "detail": [
        {
            "type": "json_invalid",
            "loc": [
                "body",
                84
            ],
            "msg": "JSON decode error",
            "input": {},
            "ctx": {
                "error": "Expecting property name enclosed in double quotes"
            }
        }
    ]
}
{
    "detail": [
        {
            "type": "too_long",
            "loc": [
                "body",
                "tags"
            ],
            "msg": "List should have at most 5 items after validation, not 6",
            "input": [
                "a",
                "b",
                "c",
                "d",
                "e",
                "f"
            ],
            "ctx": {
                "field_type": "List",
                "max_length": 5,
                "actual_length": 6
            }
        }
    ]
}

curl -s -w "\nstatus: %{http_code}\n" http://localhost:8000/prompts/99
curl -s -w "\nstatus: %{http_code}\n" -X POST http://localhost:8000/prompts -H "Content-Type: application/json" \
  -d '{"name": "course-helper", "template": "Another: {question}", "owner_email": "mitu@example.com"}'
curl -s -w "status: %{http_code}\n" -X DELETE http://localhost:8000/prompts/2
curl -s -w "\nstatus: %{http_code}\n" -X DELETE http://localhost:8000/prompts/2

{"detail":"Prompt 99 not found"}
status: 404
{"detail":"A prompt named 'course-helper' already exists"}
status: 409
status: 204
{"detail":"Prompt 2 not found"}
status: 404

import requests

BASE = "http://localhost:8000"

r = requests.post(f"{BASE}/prompts/1/render", json={"question": "What is an API?"}, timeout=5)
print(r.status_code, r.json())

r = requests.post(f"{BASE}/prompts/1/render", json={"question": ""}, timeout=5)
print(r.status_code, r.json()["detail"][0]["msg"])

200 {'prompt_id': 1, 'model': 'bitbyte-mini', 'temperature': 0.7, 'text': 'You are a friendly tutor. Answer briefly: What is an API?'}
422 String should have at least 1 character

bitbyte-prompts/
├── app/
│   ├── __init__.py      makes "app" a package
│   ├── main.py          the FastAPI app and its endpoints
│   └── schemas.py       Pydantic models: what goes in and out
├── tests/               tests (next page)
├── .gitignore           .venv, __pycache__, .env ...
├── .python-version
├── pyproject.toml       dependencies (uv) - or requirements.txt (pip)
├── uv.lock
└── README.md

from typing import Annotated

from pydantic import BaseModel, Field, ValidationError


class FeedbackIn(BaseModel):
    answer_id: Annotated[int, Field(ge=1)]
    rating: Annotated[int, Field(ge=1, le=5)]
    comment: Annotated[str | None, Field(max_length=280)] = None


print(FeedbackIn(answer_id=7, rating=5, comment="Clear and correct"))
try:
    FeedbackIn(answer_id=7, rating=6)
except ValidationError as exc:
    print(exc.errors()[0]["type"])

answer_id=7 rating=5 comment='Clear and correct'
less_than_equal

# file: answers.py
from app.main import PROMPTS, PromptId, app, find_prompt
from app.schemas import PromptCreate, PromptPublic


@app.put("/prompts/{prompt_id}")
def replace_prompt(prompt_id: PromptId, prompt: PromptCreate) -> PromptPublic:
    find_prompt(prompt_id)
    PROMPTS[prompt_id] = {"id": prompt_id, **prompt.model_dump()}
    return PROMPTS[prompt_id]

uv run fastapi run answers.py --port 8001 > answers.log 2>&1 &
curl -s --retry 20 --retry-connrefused --retry-delay 0 http://localhost:8001/health > /dev/null
curl -s -X POST http://localhost:8001/prompts -H "Content-Type: application/json" \
  -d '{"name": "explain", "template": "Explain simply: {question}", "owner_email": "nadia@example.com"}'
echo
curl -s -X PUT http://localhost:8001/prompts/1 -H "Content-Type: application/json" \
  -d '{"name": "explain", "template": "Explain like I am new to AI: {question}", "temperature": 0.4, "owner_email": "nadia@example.com"}'
echo
curl -s -X PUT http://localhost:8001/prompts/5 -H "Content-Type: application/json" \
  -d '{"name": "ghost", "template": "Nobody: {question}", "owner_email": "nadia@example.com"}'

{"name":"explain","template":"Explain simply: {question}","model":"bitbyte-mini","temperature":0.7,"tags":[],"id":1}
{"name":"explain","template":"Explain like I am new to AI: {question}","model":"bitbyte-mini","temperature":0.4,"tags":[],"id":1}
{"detail":"Prompt 5 not found"}

from pydantic import field_validator


class TaggedPrompt(BaseModel):
    tags: Annotated[list[str], Field(max_length=5)] = []

    @field_validator("tags")
    @classmethod
    def clean_tags(cls, tags: list[str]) -> list[str]:
        cleaned = [t.strip().lower() for t in tags if t.strip()]
        return list(dict.fromkeys(cleaned))     # ডুপ্লিকেট বাদ দিন, ক্রম ঠিক রাখুন


print(TaggedPrompt(tags=["Tutor", "tutor ", "short", "  "]).tags)

['tutor', 'short']