Add application file

DockerFile

@@ -0,0 +1,18 @@
+# Base image
+FROM python:3.11-slim
+
+# Set work directory
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy project files
+COPY . .
+
+# Expose the port Hugging Face expects
+EXPOSE 7860
+
+# Command to run FastAPI with uvicorn
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

app/config.py

@@ -0,0 +1,26 @@
+# app/config.py
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    # OpenAI Configuration (Required)
+    OPENAI_API_KEY: str
+
+    # Database Configuration (Required)
+    NEON_DATABASE_URL: str
+
+    # Qdrant Vector Database (Required)
+    QDRANT_URL: str
+    QDRANT_API_KEY: str
+
+    # OpenAI Model Configuration (Optional - defaults provided)
+    OPENAI_MODEL_CHAT: str = "gpt-4o-mini"
+    OPENAI_MODEL_EMBEDDING: str = "text-embedding-3-small"
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = 'utf-8'
+        extra = "ignore"  # Ignore extra env vars like legacy gemini_api_key
+
+
+settings = Settings()

app/database.py

@@ -0,0 +1,17 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.ext.declarative import declarative_base
+from app.config import settings
+
+# Use NEON_DATABASE_URL if available, otherwise fall back to DATABASE_URL
+SQLALCHEMY_DATABASE_URL = settings.NEON_DATABASE_URL or settings.DATABASE_URL or "sqlite:///./test.db"
+engine = create_engine(SQLALCHEMY_DATABASE_URL)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+Base = declarative_base()
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

app/main.py

@@ -0,0 +1,35 @@
+from dotenv import load_dotenv
+
+
+# Load environment variables FIRST
+load_dotenv()
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from app.routes import chat, translate, personalize
+from app.database import engine, Base
+from app.qdrant_client import init_qdrant_collection
+
+app = FastAPI(title="RAG Chatbot API")
+
+# CORS Configuration
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3000", "http://127.0.0.1:3000","http://localhost:3001", "http://127.0.0.1:3001"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(chat.router)
+app.include_router(translate.router)
+app.include_router(personalize.router)
+
+@app.get("/")
+async def root():
+    return {"message": "RAG Chatbot API"}
+
+@app.get("/api/health")
+async def health():
+    return {"status": "ok"}

app/models/chat.py

@@ -0,0 +1,14 @@
+from sqlalchemy import Column, Integer, String, ForeignKey, DateTime, func
+from sqlalchemy.orm import relationship
+from app.database import Base
+
+class ChatHistory(Base):
+    __tablename__ = "chat_history"
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id"))
+    message = Column(String)
+    response = Column(String)
+    timestamp = Column(DateTime, default=func.now())
+
+    user = relationship("User")

app/models/translation.py

@@ -0,0 +1,13 @@
+from sqlalchemy import Column, Integer, String, Text, DateTime
+from sqlalchemy.sql import func
+from app.database import Base
+
+
+class Translation(Base):
+    __tablename__ = "translations"
+
+    id = Column(Integer, primary_key=True, index=True)
+    cache_key = Column(String(255), unique=True, index=True, nullable=False)
+    english_text = Column(Text, nullable=False)
+    urdu_text = Column(Text, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())

app/models/user.py

@@ -0,0 +1,31 @@
+from enum import Enum
+from sqlalchemy import Column, Integer, String, Text, DateTime
+from sqlalchemy.sql import func
+from app.database import Base
+
+
+class SoftwareLevel(str, Enum):
+    """User's software development experience level"""
+    beginner = "beginner"
+    intermediate = "intermediate"
+    advanced = "advanced"
+
+
+class HardwareLevel(str, Enum):
+    """User's hardware/electronics experience level"""
+    none = "none"
+    basic = "basic"
+    experienced = "experienced"
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    username = Column(String, unique=True, index=True, nullable=True)
+    email = Column(String(255), unique=True, index=True, nullable=False)
+    hashed_password = Column(String(60), nullable=False)
+    software_level = Column(String(20), nullable=False, default="beginner")
+    hardware_level = Column(String(20), nullable=False, default="none")
+    learning_goals = Column(Text, nullable=False, default="")
+    created_at = Column(DateTime(timezone=True), server_default=func.now())

app/qdrant_client.py

@@ -0,0 +1,54 @@
+# app/qdrant_client.py
+from qdrant_client import QdrantClient
+from qdrant_client.models import Distance, VectorParams
+from app.config import settings
+
+# OpenAI text-embedding-3-small produces 1536-dimensional vectors
+EMBEDDING_DIMENSION = 1536
+
+# Initialize Qdrant client
+qdrant_client = QdrantClient(
+    url=settings.QDRANT_URL,
+    api_key=settings.QDRANT_API_KEY,
+)
+
+COLLECTION_NAME = "book_embeddings"
+
+
+def init_qdrant_collection(recreate: bool = False):
+    """Initialize Qdrant collection if it doesn't exist (or recreate if flagged)"""
+    try:
+        # Check if collection exists
+        collections = qdrant_client.get_collections().collections
+        collection_names = [col.name for col in collections]
+
+        if recreate and COLLECTION_NAME in collection_names:
+            qdrant_client.delete_collection(collection_name=COLLECTION_NAME)
+            print(f"Deleted existing Qdrant collection: {COLLECTION_NAME} (for dimension fix)")
+
+        if COLLECTION_NAME not in collection_names:
+            # Create collection with vector configuration
+            qdrant_client.create_collection(
+                collection_name=COLLECTION_NAME,
+                vectors_config=VectorParams(
+                    size=EMBEDDING_DIMENSION,  # OpenAI text-embedding-3-small dimension
+                    distance=Distance.COSINE
+                )
+            )
+            print(f"Created Qdrant collection: {COLLECTION_NAME}")
+        else:
+            # Verify dimensions match (optional safety check)
+            info = qdrant_client.get_collection(COLLECTION_NAME)
+            if info.config.params.vectors.size != EMBEDDING_DIMENSION:
+                raise ValueError(
+                    f"Collection {COLLECTION_NAME} has wrong size {info.config.params.vectors.size}; "
+                    f"expected {EMBEDDING_DIMENSION}. Recreate with flag."
+                )
+            print(f"Qdrant collection already exists with correct dims: {COLLECTION_NAME}")
+    except Exception as e:
+        print(f"Warning: Could not initialize Qdrant collection: {e}")
+
+
+def get_qdrant_client():
+    """Dependency to get Qdrant client"""
+    return qdrant_client

app/routes/chat.py

@@ -0,0 +1,60 @@
+
+
+
+
+from fastapi import APIRouter, Depends, HTTPException
+from qdrant_client import QdrantClient
+from app.qdrant_client import get_qdrant_client
+from app.schemas.chat import ChatRequest, ChatResponse, ChatSelectionRequest
+from app.services.rag_service import RAGService
+from app.services.embeddings_service import EmbeddingsService
+from app.services.openai_service import OpenAIService
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["chat"])
+
+def get_rag_service(
+    qdrant_client: QdrantClient = Depends(get_qdrant_client)
+):
+    embeddings_service = EmbeddingsService()
+    openai_service = OpenAIService()
+    return RAGService(qdrant_client, embeddings_service, openai_service)
+
+@router.post("/chat", response_model=ChatResponse)
+async def chat(
+    request: ChatRequest,
+    rag_service: RAGService = Depends(get_rag_service)
+):
+    try:
+        # Retrieve context from vector database
+        context = await rag_service.retrieve_context(request.question, top_k=3)
+        
+        # Generate response using Gemini
+        answer = await rag_service.generate_response(request.question, context)
+        
+        # Extract sources from context
+        sources = [f"Source {i+1}" for i in range(len(context))]
+        
+        return ChatResponse(answer=answer, sources=sources)
+    except Exception as e:
+        logger.error(f"Error in chat endpoint: {str(e)}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/chat-selection", response_model=ChatResponse)
+async def chat_selection(
+    request: ChatSelectionRequest,
+    rag_service: RAGService = Depends(get_rag_service)
+):
+    try:
+        # Use selected text as primary context
+        context = [request.selected_text]
+        
+        # Generate response
+        answer = await rag_service.generate_response(request.question, context)
+        
+        return ChatResponse(answer=answer, sources=["Selected Text"])
+    except Exception as e:
+        logger.error(f"Error in chat_selection endpoint: {str(e)}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))

app/routes/personalize.py

@@ -0,0 +1,59 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from app.database import get_db
+from app.models.user import User
+from app.schemas.personalize import PersonalizeRequest, PersonalizeResponse
+from app.services.openai_service import OpenAIService
+import logging
+import json
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api", tags=["personalization"])
+
+
+@router.post("/personalize", response_model=PersonalizeResponse)
+async def personalize_content(
+    request: PersonalizeRequest,
+    db: Session = Depends(get_db)
+):
+    """
+    Personalize content based on user's background.
+
+    - Fetches user profile from database
+    - Uses Gemini to adapt content complexity based on:
+      * software_level (beginner/intermediate/advanced)
+      * hardware_level (none/basic/experienced)
+      * learning_goals (free text)
+    - Returns personalized content with description of adjustments
+    """
+    # Fetch user profile
+    user = db.query(User).filter(User.id == request.user_id).first()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    # Personalize via OpenAI SDK + Gemini
+    try:
+        openai_service = OpenAIService()
+        result = await openai_service.personalize_content(
+            content=request.content,
+            software_level=user.software_level,
+            hardware_level=user.hardware_level,
+            learning_goals=user.learning_goals or ""
+        )
+    except json.JSONDecodeError as e:
+        logger.error(f"Invalid JSON from Gemini: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail="Invalid response from personalization service"
+        )
+    except Exception as e:
+        logger.error(f"Gemini personalization error: {e}")
+        raise HTTPException(
+            status_code=503,
+            detail="Personalization service temporarily unavailable"
+        )
+
+    return PersonalizeResponse(
+        personalized_content=result.get("personalized_content", ""),
+        adjustments_made=result.get("adjustments_made", "")
+    )

app/routes/translate.py

@@ -0,0 +1,59 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from sqlalchemy.exc import IntegrityError
+from app.database import get_db
+from app.models.translation import Translation
+from app.schemas.translate import TranslateRequest, TranslateResponse
+from app.services.openai_service import OpenAIService
+import logging
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api", tags=["translation"])
+
+
+@router.post("/translate/urdu", response_model=TranslateResponse)
+async def translate_to_urdu(
+    request: TranslateRequest,
+    db: Session = Depends(get_db)
+):
+    """
+    Translate English text to Urdu.
+
+    - Checks cache first for existing translation
+    - If not cached, calls Gemini for translation
+    - Stores new translations in database for future requests
+    """
+    # T007: Check cache first
+    cached = db.query(Translation).filter_by(cache_key=request.cache_key).first()
+    if cached:
+        return TranslateResponse(urdu_text=cached.urdu_text, cached=True)
+
+    # Perform translation via OpenAI SDK + Gemini
+    try:
+        openai_service = OpenAIService()
+        urdu_text = await openai_service.translate_to_urdu(request.content)
+    except Exception as e:
+        logger.error(f"Gemini translation error: {e}")
+        raise HTTPException(status_code=503, detail="Translation service temporarily unavailable")
+
+    # T008 & T009: Store in cache with race condition handling
+    try:
+        translation = Translation(
+            cache_key=request.cache_key,
+            english_text=request.content,
+            urdu_text=urdu_text
+        )
+        db.add(translation)
+        db.commit()
+    except IntegrityError:
+        db.rollback()
+        # Race condition - another request cached this key
+        cached = db.query(Translation).filter_by(cache_key=request.cache_key).first()
+        if cached:
+            return TranslateResponse(urdu_text=cached.urdu_text, cached=True)
+    except Exception as e:
+        logger.error(f"Database error: {e}")
+        # Return translation even if caching fails
+        return TranslateResponse(urdu_text=urdu_text, cached=False)
+
+    return TranslateResponse(urdu_text=urdu_text, cached=False)

app/schemas/auth.py

@@ -0,0 +1,51 @@
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, EmailStr, Field, field_validator
+from app.models.user import SoftwareLevel, HardwareLevel
+
+
+class SignupRequest(BaseModel):
+    """Request schema for user registration"""
+    email: EmailStr
+    password: str = Field(..., min_length=8, description="Password must be at least 8 characters")
+    software_level: SoftwareLevel
+    hardware_level: HardwareLevel
+    learning_goals: str = Field(..., max_length=1000, description="Learning objectives (max 1000 chars)")
+
+    @field_validator('email')
+    @classmethod
+    def normalize_email(cls, v: str) -> str:
+        """Normalize email to lowercase"""
+        return v.lower().strip()
+
+
+class SigninRequest(BaseModel):
+    """Request schema for user authentication"""
+    email: EmailStr
+    password: str
+
+    @field_validator('email')
+    @classmethod
+    def normalize_email(cls, v: str) -> str:
+        """Normalize email to lowercase"""
+        return v.lower().strip()
+
+
+class TokenResponse(BaseModel):
+    """Response schema for successful authentication"""
+    access_token: str
+    token_type: str = "bearer"
+
+
+class UserResponse(BaseModel):
+    """Response schema for user profile data"""
+    id: int
+    email: str
+    username: Optional[str] = None
+    software_level: str
+    hardware_level: str
+    learning_goals: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True

app/schemas/chat.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel
+from typing import List, Optional
+from datetime import datetime
+
+class Message(BaseModel):
+    content: str
+    role: str
+
+class ChatRequest(BaseModel):
+    question: str
+    user_id: Optional[int] = None
+
+class ChatResponse(BaseModel):
+    answer: str
+    sources: List[str] = []
+
+class ChatSelectionRequest(BaseModel):
+    question: str
+    selected_text: str
+    user_id: Optional[int] = None
+
+class ChatSelectionResponse(BaseModel):
+    response: str

app/schemas/personalize.py

@@ -0,0 +1,28 @@
+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

app/schemas/translate.py

@@ -0,0 +1,25 @@
+from pydantic import BaseModel, field_validator
+
+
+class TranslateRequest(BaseModel):
+    content: str
+    cache_key: str
+
+    @field_validator('content')
+    @classmethod
+    def content_not_empty(cls, v):
+        if not v or not v.strip():
+            raise ValueError('Content cannot be empty')
+        return v.strip()
+
+    @field_validator('cache_key')
+    @classmethod
+    def cache_key_not_empty(cls, v):
+        if not v or not v.strip():
+            raise ValueError('Cache key cannot be empty')
+        return v.strip()
+
+
+class TranslateResponse(BaseModel):
+    urdu_text: str
+    cached: bool

app/services/embeddings_service.py

@@ -0,0 +1,19 @@
+# app/services/embeddings_service.py
+from openai import OpenAI
+from app.config import settings
+
+
+class EmbeddingsService:
+    def __init__(self):
+        self.client = OpenAI(
+            api_key=settings.OPENAI_API_KEY
+        )
+        self.model = settings.OPENAI_MODEL_EMBEDDING
+
+    def create_embedding(self, text: str):
+        """Generate embedding for text using OpenAI API."""
+        response = self.client.embeddings.create(
+            model=self.model,
+            input=text
+        )
+        return response.data[0].embedding

app/services/openai_service.py

@@ -0,0 +1,102 @@
+# app/services/openai_service.py
+from openai import OpenAI
+from app.config import settings
+from typing import List
+import json
+
+
+class OpenAIService:
+    def __init__(self):
+        self.client = OpenAI(
+            api_key=settings.OPENAI_API_KEY
+        )
+        self.model = settings.OPENAI_MODEL_CHAT
+
+    async def get_chat_response(self, prompt: str, history: List[dict] = None) -> str:
+        """Generate chat response using OpenAI API."""
+        messages = []
+
+        if history:
+            for msg in history:
+                if msg["role"] != "system":
+                    messages.append({
+                        "role": msg["role"],
+                        "content": msg["content"]
+                    })
+
+        messages.append({"role": "user", "content": prompt})
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages
+        )
+        return response.choices[0].message.content
+
+    async def translate_to_urdu(self, content: str) -> str:
+        """Translate English content to Urdu using OpenAI API."""
+        messages = [
+            {
+                "role": "system",
+                "content": "You are a professional translator. Translate the following English text to Urdu. Maintain technical terms. Provide only the Urdu translation without any explanation or additional text."
+            },
+            {
+                "role": "user",
+                "content": content
+            }
+        ]
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages
+        )
+        return response.choices[0].message.content
+
+    async def personalize_content(
+        self,
+        content: str,
+        software_level: str,
+        hardware_level: str,
+        learning_goals: str
+    ) -> dict:
+        """Personalize content based on user's background."""
+        system_prompt = f"""You are an expert educational content adapter. Your task is to personalize the following content based on the user's background.
+
+USER PROFILE:
+- Software/Programming Level: {software_level}
+- Hardware/Electronics Level: {hardware_level}
+- Learning Goals: {learning_goals if learning_goals else 'Not specified'}
+
+PERSONALIZATION RULES:
+
+For Software Level:
+- beginner: Add detailed explanations, use simpler terminology, break down complex concepts, provide examples
+- intermediate: Maintain moderate complexity, brief explanations for advanced concepts only
+- advanced: Add technical depth, skip basic explanations, use precise technical terminology
+
+For Hardware Level:
+- none: Explain all hardware concepts from scratch, use analogies
+- basic: Brief hardware explanations, define technical terms
+- experienced: Use technical hardware terminology without explanation
+
+If learning goals are specified, emphasize and connect content to those objectives.
+
+OUTPUT FORMAT:
+Respond with a JSON object containing exactly two fields:
+1. "personalized_content": The adapted content
+2. "adjustments_made": A brief description of what changes were made
+
+Example response format:
+{{"personalized_content": "...", "adjustments_made": "..."}}"""
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": content}
+        ]
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages
+        )
+
+        result = json.loads(response.choices[0].message.content)
+        return result

app/services/rag_service.py

@@ -0,0 +1,75 @@
+
+# import os
+# from qdrant_client import QdrantClient
+# from qdrant_client.models import NamedVector
+# from typing import List
+
+# from app.services.openai_service import OpenAIService
+# from app.services.embeddings_service import EmbeddingsService
+
+# class RAGService:
+#     def __init__(self, qdrant_client: QdrantClient, embeddings_service: EmbeddingsService, gemini_service: OpenAIService):
+#         self.qdrant_client = qdrant_client
+#         self.embeddings_service = embeddings_service
+#         self.gemini_service = gemini_service
+#         self.collection_name = os.getenv("QDRANT_COLLECTION_NAME", "book_embeddings")
+
+#     async def retrieve_context(self, query: str, top_k: int = 3) -> List[str]:
+#         query_vector = self.embeddings_service.create_embedding(query)
+
+#         search_result = self.qdrant_client.query_points(
+#             collection_name=self.collection_name,
+#             query=query_vector,
+#             limit=top_k,
+#             with_payload=True,
+#         ).points
+
+#         context = [point.payload.get("content", "") for point in search_result if point.payload]
+#         return context
+
+#     async def generate_response(self, query: str, context: List[str]) -> str:
+#         full_prompt = f"""Context: {' '.join(context)}
+
+# Question: {query}
+
+# Answer:"""
+#         response = await self.gemini_service.get_chat_response(full_prompt)
+#         return response
+
+
+import os
+from qdrant_client import QdrantClient
+from qdrant_client.models import NamedVector
+from typing import List
+
+from app.services.openai_service import OpenAIService
+from app.services.embeddings_service import EmbeddingsService
+
+class RAGService:
+    def __init__(self, qdrant_client: QdrantClient, embeddings_service: EmbeddingsService, gemini_service: OpenAIService):
+        self.qdrant_client = qdrant_client
+        self.embeddings_service = embeddings_service
+        self.gemini_service = gemini_service
+        self.collection_name = os.getenv("QDRANT_COLLECTION_NAME", "book_embeddings")
+
+    async def retrieve_context(self, query: str, top_k: int = 3) -> List[str]:
+        query_vector = self.embeddings_service.create_embedding(query)
+
+        search_result = self.qdrant_client.query_points(
+            collection_name=self.collection_name,
+            query=query_vector,
+            limit=top_k,
+            with_payload=True,
+        ).points
+
+        context = [point.payload.get("content", "") for point in search_result if point.payload]
+        return context
+
+    async def generate_response(self, query: str, context: List[str]) -> str:
+        full_prompt = f"""Context: {' '.join(context)}
+
+Question: {query}
+
+Answer:"""
+        response = await self.gemini_service.get_chat_response(full_prompt)
+        return response

history/prompts/004-urdu-translation/001-urdu-translation-spec.spec.prompt.md

@@ -0,0 +1,76 @@
+---
+id: 001
+title: Urdu Translation API Spec Creation
+stage: spec
+date: 2025-12-14
+surface: agent
+model: claude-opus-4-5-20251101
+feature: 004-urdu-translation
+branch: 004-urdu-translation
+user: user
+command: /sp.specify
+labels: ["translation", "urdu", "openai", "caching", "api"]
+links:
+  spec: specs/004-urdu-translation/spec.md
+  ticket: null
+  adr: null
+  pr: null
+files:
+  - specs/004-urdu-translation/spec.md
+  - specs/004-urdu-translation/checklists/requirements.md
+  - history/prompts/004-urdu-translation/001-urdu-translation-spec.spec.prompt.md
+tests:
+  - N/A - specification phase
+---
+
+## Prompt
+
+Add Urdu translation API endpoint.
+
+**Feature:**
+- POST /api/translate/urdu
+- Request: {content: string, cache_key: string}
+- Use OpenAI GPT-4 for translation
+- Cache translations in Neon database (translations table)
+- Response: {urdu_text: string, cached: boolean}
+
+**Tables:**
+- translations: id, cache_key, english_text, urdu_text, created_at
+
+Files:
+- app/routes/translate.py
+- app/models/translation.py
+
+## Response snapshot
+
+Created feature specification for Urdu Translation API on branch `004-urdu-translation`:
+
+1. **User Stories (3 total)**:
+   - P1: Translate English Content to Urdu - send English text and receive Urdu translation via OpenAI GPT-4
+   - P1: Retrieve Cached Translations - return cached translations without making new AI requests
+   - P2: Translation Data Persistence - store translations in database for retrieval and audit
+
+2. **Functional Requirements (9 total)**: FR-001 through FR-009 covering POST endpoint at /api/translate/urdu, request validation, cache lookup, OpenAI GPT-4 translation, database storage, response format with cached boolean, and error handling.
+
+3. **Key Entity**: Translation with id, cache_key, english_text, urdu_text, and created_at fields.
+
+4. **Success Criteria (5 total)**: Measurable outcomes including new translations < 10 sec, cached responses < 500ms, 100% cache hit rate for existing keys, acceptable translation quality, and 50 concurrent requests support.
+
+5. **Edge Cases**: AI service unavailability, special characters/emoji handling, database connection failures, concurrent requests with same cache key.
+
+6. **Quality Checklist**: All items passed - no clarifications needed, technology-agnostic, testable requirements.
+
+## Outcome
+
+- Status: Specification created, ready for planning phase
+- Tests: N/A - specification phase
+- Files: spec.md, requirements.md checklist created
+- Next prompts: /sp.plan or /sp.clarify
+- Reflection: User requirements were clear and comprehensive, enabling complete spec without clarification markers
+
+## Evaluation notes (flywheel)
+
+- Failure modes observed: None - requirements were explicit with clear table schema and API contract
+- Graders run and results (PASS/FAIL): Checklist validation PASS (all items checked)
+- Prompt variant (if applicable): N/A
+- Next experiment (smallest change to try): N/A

history/prompts/004-urdu-translation/002-urdu-translation-plan.plan.prompt.md

@@ -0,0 +1,81 @@
+---
+id: 002
+title: Urdu Translation Implementation Plan
+stage: plan
+date: 2025-12-14
+surface: agent
+model: claude-opus-4-5-20251101
+feature: 004-urdu-translation
+branch: 004-urdu-translation
+user: user
+command: /sp.plan
+labels: ["translation", "urdu", "openai", "architecture", "api-design"]
+links:
+  spec: specs/004-urdu-translation/spec.md
+  ticket: null
+  adr: null
+  pr: null
+files:
+  - specs/004-urdu-translation/plan.md
+  - specs/004-urdu-translation/research.md
+  - specs/004-urdu-translation/data-model.md
+  - specs/004-urdu-translation/contracts/openapi.yaml
+  - specs/004-urdu-translation/quickstart.md
+  - history/prompts/004-urdu-translation/002-urdu-translation-plan.plan.prompt.md
+tests:
+  - N/A - planning phase
+---
+
+## Prompt
+
+/sp.plan
+
+Execute the implementation planning workflow for the Urdu Translation API feature (004-urdu-translation).
+
+## Response snapshot
+
+Created implementation plan for Urdu Translation API with the following artifacts:
+
+1. **research.md**: Technical decisions resolved
+   - OpenAI GPT-4 for translation (quality for Urdu script)
+   - Database-first caching strategy with cache_key lookup
+   - Error handling patterns matching existing codebase
+   - Race condition handling with UNIQUE constraint
+
+2. **data-model.md**: Translation entity defined
+   - Fields: id, cache_key (unique), english_text, urdu_text, created_at
+   - Indexes: Primary key on id, unique index on cache_key
+   - SQLAlchemy model ready for implementation
+
+3. **contracts/openapi.yaml**: API specification
+   - POST /api/translate/urdu endpoint
+   - Request: {content, cache_key}
+   - Response: {urdu_text, cached}
+   - Error responses: 400, 500, 503
+
+4. **quickstart.md**: Developer guide
+   - curl examples for testing
+   - Cache key best practices
+   - Files to implement list
+
+5. **plan.md**: Implementation plan
+   - Architecture diagram
+   - Code snippets for all components
+   - 6-step implementation order
+   - Error handling strategy
+   - Testing strategy
+
+## Outcome
+
+- Status: Planning complete, ready for task generation
+- Tests: N/A - planning phase
+- Files: 5 planning artifacts created
+- Next prompts: /sp.tasks to generate implementation tasks
+- Reflection: Existing codebase patterns (OpenAIService, SQLAlchemy, FastAPI) enabled clear implementation path
+
+## Evaluation notes (flywheel)
+
+- Failure modes observed: None - clear requirements and existing patterns
+- Graders run and results (PASS/FAIL): Constitution compliance PASS
+- Prompt variant (if applicable): N/A
+- Next experiment (smallest change to try): N/A