specs/005-content-personalize/research.md

Research: Content Personalization API

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

Research Summary

This feature leverages existing infrastructure and established patterns from the codebase. No external research was required as all technical decisions align with current implementations.

---

Decision 1: AI Prompt Engineering for Personalization

Decision: Use a structured system prompt that includes user profile context and personalization rules to guide content adaptation.

Rationale:

• The existing translate_to_urdu method demonstrates the pattern of using system prompts for specific tasks
• Including user profile (software_level, hardware_level, learning_goals) directly in the system prompt gives the AI full context
• Requesting both personalized content AND adjustments_made in a structured format ensures consistent responses

Alternatives considered:

1. Multi-step approach: First analyze content, then personalize - adds latency and complexity
2. Fine-tuned model: Would require training data and ongoing maintenance - overkill for this use case
3. Rule-based preprocessing + AI: Mix of hardcoded rules and AI - harder to maintain consistency

Implementation approach:

System prompt structure:
1. Role definition (expert content adapter)
2. User profile context (levels, goals)
3. Personalization rules (from spec PL-001 to PL-007)
4. Output format instruction (personalized content + adjustments made)

---

Decision 2: Response Structure

Decision: Return JSON with personalized_content (string) and adjustments_made (string) fields.

Rationale:

• Matches spec requirement FR-003
• adjustments_made provides transparency about what changed
• String format for adjustments is flexible for various adaptation descriptions

Alternatives considered:

1. Structured adjustments object: Would require predefined categories - less flexible
2. Streaming response: Adds complexity, not needed for typical content sizes
3. Include original content: Redundant - client already has it

---

Decision 3: Content Length Handling

Decision: Accept content up to 50,000 characters, return 400 error for content exceeding this limit.

Rationale:

• OpenAI GPT-4 has ~128K token context window - 50K chars is well within limits
• Matches edge case specification for long content
• Provides predictable behavior for clients

Alternatives considered:

1. Chunking: Split long content and process in parts - adds complexity, may break context
2. No limit: Risk of timeout or token limit errors from OpenAI
3. Lower limit (10K): Too restrictive for comprehensive educational content

---

Decision 4: User Lookup Pattern

Decision: Query user by ID from existing User model, return 404 if not found.

Rationale:

• User model already exists with required fields (software_level, hardware_level, learning_goals)
• Consistent with REST patterns for resource lookup
• Clear error handling specified in FR-010

Implementation:

user = db.query(User).filter(User.id == request.user_id).first()
if not user:
    raise HTTPException(status_code=404, detail="User not found")

---

Decision 5: OpenAI Model Selection

Decision: Use GPT-4 for personalization (consistent with existing translate service).

Rationale:

• GPT-4 provides superior reasoning for content adaptation
• Content personalization requires understanding of complexity levels
• Existing translate_to_urdu uses GPT-4 successfully

Alternatives considered:

1. GPT-4o-mini: Faster and cheaper but may produce lower quality adaptations
2. GPT-3.5: Significantly less capable at nuanced content modification
3. Claude: Would require additional API integration

---

Technical Context Resolution

Aspect	Status	Resolution
Framework	✅ Resolved	FastAPI (existing)
Database	✅ Resolved	Neon PostgreSQL via SQLAlchemy (existing)
AI Service	✅ Resolved	OpenAI GPT-4 (existing SDK, follow translate pattern)
User Model	✅ Resolved	Existing User model has all required fields
Authentication	✅ Resolved	Out of scope per spec - endpoint assumes valid user_id
Response Format	✅ Resolved	JSON with personalized_content + adjustments_made

---

Dependencies Identified

Dependency	Status	Notes
OpenAI SDK	✅ Exists	Already configured in openai_service.py
User Model	✅ Exists	Has software_level, hardware_level, learning_goals
Database	✅ Exists	SQLAlchemy with Neon PostgreSQL
FastAPI	✅ Exists	Core framework

---

Risk Assessment

Risk	Likelihood	Impact	Mitigation
OpenAI API latency > 15s	Medium	High	Set timeout, return 503 on failure
Inconsistent personalization quality	Low	Medium	Clear prompt engineering, test with various profiles
Large content processing	Low	Low	50K char limit, appropriate error messages
User not found	Low	Low	Clear 404 response

---

No Further Research Needed

All NEEDS CLARIFICATION items from specification have been resolved through this research. The feature can proceed to design phase.