specs/005-content-personalize/data-model.md

Data Model: Content Personalization API

Feature Branch: 005-content-personalize Created: 2025-12-14 Status: Complete

Overview

This feature uses the existing User model and introduces request/response schemas only. No new database tables are required.

---

Existing Entity: User

The User entity already contains all fields needed for personalization.

Location: app/models/user.py

┌─────────────────────────────────────────────┐
│                   User                       │
├─────────────────────────────────────────────┤
│ id: Integer (PK)                            │
│ username: String (nullable, unique)         │
│ email: String(255) (unique, not null)       │
│ hashed_password: String(60) (not null)      │
│ software_level: String(20) (default: "beginner")     │
│ hardware_level: String(20) (default: "none")         │
│ learning_goals: Text (default: "")          │
│ created_at: DateTime (auto)                 │
└─────────────────────────────────────────────┘

Relevant Fields for Personalization

Field	Type	Values	Usage
software_level	String(20)	"beginner", "intermediate", "advanced"	Determines code/software content complexity
hardware_level	String(20)	"none", "basic", "experienced"	Determines hardware concept explanation depth
learning_goals	Text	Free-form	Used to emphasize relevant topics

Enums (Reference)

class SoftwareLevel(str, Enum):
    beginner = "beginner"
    intermediate = "intermediate"
    advanced = "advanced"

class HardwareLevel(str, Enum):
    none = "none"
    basic = "basic"
    experienced = "experienced"

---

New Schema: PersonalizeRequest

Purpose: Validate incoming personalization requests

Location: app/schemas/personalize.py

┌─────────────────────────────────────────────┐
│            PersonalizeRequest               │
├─────────────────────────────────────────────┤
│ content: str (required, non-empty)          │
│ user_id: int (required, positive)           │
└─────────────────────────────────────────────┘

Validation Rules

Field	Rule	Error
content	Non-empty after strip	"Content cannot be empty"
content	Max 50,000 characters	"Content exceeds maximum length of 50000 characters"
user_id	Positive integer	"User ID must be a positive integer"

---

New Schema: PersonalizeResponse

Purpose: Structure the API response

Location: app/schemas/personalize.py

┌─────────────────────────────────────────────┐
│            PersonalizeResponse              │
├─────────────────────────────────────────────┤
│ personalized_content: str                   │
│ adjustments_made: str                       │
└─────────────────────────────────────────────┘

Field Descriptions

Field	Description	Example
personalized_content	The content adapted for the user's level	Full adapted text
adjustments_made	Human-readable description of changes	"Simplified technical terminology, added explanations for variables and loops, included beginner-friendly examples"

---

Entity Relationships

┌─────────────────┐          ┌─────────────────────────┐
│      User       │ ◄─────── │   PersonalizeRequest    │
│                 │  user_id │                         │
│ id (PK)         │          │ content                 │
│ software_level  │          │ user_id                 │
│ hardware_level  │          └─────────────────────────┘
│ learning_goals  │
└─────────────────┘
         │
         │ Profile data used for
         ▼
┌─────────────────────────────────────────────┐
│             OpenAI API Call                  │
│                                              │
│  System: Personalization rules + user profile│
│  User: Original content                      │
│                                              │
│  Returns: Adapted content + adjustments      │
└─────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────┐
│   PersonalizeResponse   │
│                         │
│ personalized_content    │
│ adjustments_made        │
└─────────────────────────┘

---

Data Flow

1. Request arrives with content and user_id
2. Validation ensures content is non-empty and within limits
3. User lookup retrieves profile from database by user_id
4. Personalization sends content + profile to OpenAI
5. Response returns adapted content and adjustment description

---

No Database Migrations Required

This feature:

• Uses existing User table (no schema changes)
• Does not persist personalized content (per spec - out of scope)
• Only requires Pydantic schemas for request/response validation

---

Schema Implementation

# app/schemas/personalize.py

from pydantic import BaseModel, field_validator


class PersonalizeRequest(BaseModel):
    content: str
    user_id: int

    @field_validator('content')
    @classmethod
    def content_not_empty(cls, v):
        if not v or not v.strip():
            raise ValueError('Content cannot be empty')
        v = v.strip()
        if len(v) > 50000:
            raise ValueError('Content exceeds maximum length of 50000 characters')
        return v

    @field_validator('user_id')
    @classmethod
    def user_id_positive(cls, v):
        if v <= 0:
            raise ValueError('User ID must be a positive integer')
        return v


class PersonalizeResponse(BaseModel):
    personalized_content: str
    adjustments_made: str