feat: add chat streaming endpoint and related schemas for OpenAI integration

backend/app/api/v1/endpoints/chat.py

@@ -0,0 +1,88 @@
+import json
+import logging
+from typing import AsyncGenerator
+
+from fastapi import APIRouter, HTTPException, status
+from fastapi.responses import StreamingResponse
+from openai import OpenAI, APIConnectionError
+
+from ....core.config import settings
+from ....schemas.chat import ChatRequest, Message
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/chat", tags=["chat"])
+
+# Create a singleton OpenAI client instance.
+client = OpenAI(api_key=settings.OPENAI_API_KEY, timeout=30.0)
+
+
+async def _stream_text(messages: list[Message]) -> AsyncGenerator[str, None]:
+    """Internal helper that yields text deltas as server-sent-events."""
+
+    # Add a default system message as first instruction.
+    system_msg = {
+        "role": "system",
+        "content": (
+            "You are an AI learning assistant for PlayGo AI, an educational platform. "
+            "Your goal is to help students learn and understand various subjects. "
+            "Provide clear, concise, and accurate explanations."
+        ),
+    }
+
+    formatted_messages = [system_msg] + [msg.model_dump() for msg in messages]
+
+    try:
+        stream = client.chat.completions.create(
+            model="gpt-3.5-turbo",
+            messages=formatted_messages,
+            temperature=0.7,
+            stream=True,
+        )
+
+        # The new Python SDK returns an iterator of events
+        for chunk in stream:
+            for choice in chunk.choices:
+                # Skip explicit finished signal – handled after loop
+                if choice.finish_reason == "stop":
+                    continue
+
+                # Emit the delta as JSON-encoded string prefixed with 0: (Vercel AI convention)
+                yield f"0:{json.dumps(choice.delta.content)}\n"
+
+        # When the stream is exhausted include usage metadata
+        usage = stream.usage if hasattr(stream, "usage") else None
+        if usage:
+            payload = {
+                "finishReason": "stop",
+                "usage": {
+                    "promptTokens": usage.prompt_tokens,
+                    "completionTokens": usage.completion_tokens,
+                },
+            }
+            yield f"d:{json.dumps(payload)}\n"
+
+    except APIConnectionError as e:
+        logger.error("OpenAI connection error: %s", str(e))
+        yield f"Error: Connection error – {str(e)}"
+    except Exception as e:
+        logger.exception("Unexpected error during streaming chat")
+        yield f"Error: {str(e)}"
+
+
+@router.post("/stream")
+async def chat_stream(request: ChatRequest):
+    """Streaming chat endpoint returning SSE-style chunks compatible with Vercel AI."""
+
+    if not settings.OPENAI_API_KEY:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="OPENAI_API_KEY is not configured on the server.",
+        )
+
+    response = StreamingResponse(
+        _stream_text(request.messages),
+    )
+    # Vercel AI convention header so front-end recognises a streamed response
+    response.headers["x-vercel-ai-data-stream"] = "v1"
+    return response 

backend/app/api/v1/router.py

@@ -1,8 +1,10 @@
 from fastapi import APIRouter
 
 from .endpoints.images import router as images_router
+from .endpoints.chat import router as chat_router
 
 api_router = APIRouter()
 
 # Include all endpoint routers
 api_router.include_router(images_router)
+api_router.include_router(chat_router)

backend/app/schemas/chat.py

@@ -0,0 +1,16 @@
+from typing import List
+
+from pydantic import BaseModel
+
+
+class Message(BaseModel):
+    """Represents a single message in the chat conversation"""
+
+    content: str
+    role: str
+
+
+class ChatRequest(BaseModel):
+    """Schema for chat completion request body"""
+
+    messages: List[Message] 

backend/requirements.txt

@@ -2,5 +2,5 @@ fastapi==0.104.1
 uvicorn[standard]==0.24.0
 pydantic==2.5.0
 pydantic-settings==2.1.0
-openai==1.82.0
+openai==1.8.2
 python-dotenv==1.0.0