Deploy SkillBridge Backend

.env.example

@@ -0,0 +1,6 @@
+# Copy this file to .env and fill in your values
+# DO NOT commit .env to version control
+
+SUPABASE_URL=https://your-project-ref.supabase.co
+SUPABASE_SERVICE_KEY=your-service-role-key-here
+GROQ_API_KEY=your-groq-api-key-here

Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install dependencies first (cached layer)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# HuggingFace Spaces requires port 7860
+EXPOSE 7860
+
+# Start the FastAPI server
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

db/supabase_client.py

@@ -0,0 +1,18 @@
+import os
+from supabase import create_client, Client
+from dotenv import load_dotenv
+
+load_dotenv()
+
+SUPABASE_URL: str = os.environ["SUPABASE_URL"]
+SUPABASE_SERVICE_KEY: str = os.environ["SUPABASE_SERVICE_KEY"]
+
+_client: Client | None = None
+
+
+def get_supabase_client() -> Client:
+    """Return a cached Supabase client using the service role key."""
+    global _client
+    if _client is None:
+        _client = create_client(SUPABASE_URL, SUPABASE_SERVICE_KEY)
+    return _client

main.py

@@ -0,0 +1,59 @@
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from routes import skills, matches, chat
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Load the sentence-transformers model once at startup.
+    Importing embedder triggers the module-level SentenceTransformer() call.
+    """
+    logger.info("Loading sentence-transformers model...")
+    import services.embedder  # noqa: F401 — side-effect import triggers model load
+    logger.info("Model ready. SkillBridge API is live.")
+    yield
+    logger.info("Shutting down.")
+
+
+app = FastAPI(
+    title="SkillBridge API",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# ── CORS ─────────────────────────────────────────────────────────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:3000",
+        "https://*.vercel.app",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Routers ───────────────────────────────────────────────────────────────────
+app.include_router(skills.router)
+app.include_router(matches.router)
+app.include_router(chat.router)
+
+
+# ── Health check ──────────────────────────────────────────────────────────────
+@app.get("/health", tags=["health"])
+async def health() -> dict:
+    return {"status": "ok"}
+
+
+# ── Entry point (used by Dockerfile CMD) ─────────────────────────────────────
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host="0.0.0.0", port=7860, reload=False)

requirements.txt

@@ -0,0 +1,8 @@
+fastapi==0.109.0
+uvicorn==0.27.0
+sentence-transformers==2.3.1
+supabase==2.3.4
+groq==0.4.2
+python-dotenv==1.0.0
+sse-starlette==1.8.2
+pydantic==2.5.3

routes/chat.py

@@ -0,0 +1,47 @@
+from fastapi import APIRouter
+from fastapi.responses import Response
+from pydantic import BaseModel
+from sse_starlette.sse import EventSourceResponse
+
+from services.ai_coach import get_coach_response
+
+router = APIRouter(prefix="/api/v1/chat", tags=["chat"])
+
+
+# ── Request model ────────────────────────────────────────────────────────────
+
+class MessageItem(BaseModel):
+    sender_id: str
+    content: str
+
+
+class CoachRequest(BaseModel):
+    session_id: str
+    messages: list[MessageItem]
+    message_count: int
+
+
+# ── Endpoint ─────────────────────────────────────────────────────────────────
+
+@router.post("/coach")
+async def coach(payload: CoachRequest) -> Response:
+    """
+    Stream the AI Coach response via Server-Sent Events.
+    Only fires when message_count is divisible by 4 (every 4th message).
+    Returns 204 No Content when the coach is not due to speak.
+    """
+    if payload.message_count % 4 != 0 or payload.message_count == 0:
+        return Response(status_code=204)
+
+    messages_dicts: list[dict] = [
+        {"sender_id": m.sender_id, "content": m.content}
+        for m in payload.messages
+    ]
+
+    async def event_generator():
+        async for chunk in get_coach_response(messages_dicts):
+            yield {"data": chunk}
+        # Signal stream completion to the client
+        yield {"data": "[DONE]"}
+
+    return EventSourceResponse(event_generator())

routes/matches.py

@@ -0,0 +1,90 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from db.supabase_client import get_supabase_client
+
+router = APIRouter(prefix="/api/v1/matches", tags=["matches"])
+
+
+# ── Response model ───────────────────────────────────────────────────────────
+
+class MatchResponse(BaseModel):
+    id: str
+    score: float
+    status: str
+    skill_offered_title: str
+    skill_needed_title: str
+    other_user_name: str
+    other_user_id: str
+    chat_session_id: str
+    created_at: str
+
+
+# ── Endpoint ─────────────────────────────────────────────────────────────────
+
+@router.get("/{user_id}", response_model=list[MatchResponse])
+async def get_matches(user_id: str) -> list[MatchResponse]:
+    """
+    Return all pending/accepted matches where the user is either teacher or
+    learner. Joins with profiles, skills, and chat_sessions so the frontend
+    has everything it needs to render the match card and navigate to the chat.
+    """
+    client = get_supabase_client()
+
+    result = (
+        client.table("matches")
+        .select(
+            "id, score, status, created_at, "
+            "teacher_id, learner_id, "
+            "skills_offered(title), "
+            "skills_needed(title), "
+            "chat_sessions(id)"
+        )
+        .or_(f"teacher_id.eq.{user_id},learner_id.eq.{user_id}")
+        .neq("status", "rejected")
+        .order("created_at", desc=True)
+        .execute()
+    )
+
+    if not result.data:
+        return []
+
+    matches: list[MatchResponse] = []
+    for row in result.data:
+        # Determine which side the requesting user is on
+        is_teacher: bool = row["teacher_id"] == user_id
+        other_user_id: str = row["learner_id"] if is_teacher else row["teacher_id"]
+
+        # Fetch the other user's profile name
+        profile_result = (
+            client.table("profiles")
+            .select("name")
+            .eq("id", other_user_id)
+            .single()
+            .execute()
+        )
+        other_name: str = (
+            profile_result.data["name"] if profile_result.data else "Unknown"
+        )
+
+        # chat_sessions is a list (one-to-many relation) — take the first
+        chat_sessions = row.get("chat_sessions") or []
+        if not chat_sessions:
+            continue
+        chat_session_id: str = chat_sessions[0]["id"]
+
+        matches.append(
+            MatchResponse(
+                id=row["id"],
+                score=row["score"],
+                status=row["status"],
+                skill_offered_title=row["skills_offered"]["title"],
+                skill_needed_title=row["skills_needed"]["title"],
+                other_user_name=other_name,
+                other_user_id=other_user_id,
+                chat_session_id=chat_session_id,
+                created_at=row["created_at"],
+            )
+        )
+
+    return matches

routes/skills.py

@@ -0,0 +1,120 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from db.supabase_client import get_supabase_client
+from services.embedder import encode_text
+from services.matcher import find_matches, create_match_if_qualified
+
+router = APIRouter(prefix="/api/v1/skills", tags=["skills"])
+
+
+# ── Request / Response models ────────────────────────────────────────────────
+
+class SkillOfferRequest(BaseModel):
+    user_id: str
+    title: str
+    description: str = ""
+
+
+class SkillNeedRequest(BaseModel):
+    user_id: str
+    title: str
+    description: str = ""
+
+
+class SkillResponse(BaseModel):
+    id: str
+    user_id: str
+    title: str
+    description: str
+    match: dict | None = None
+
+
+# ── Endpoints ────────────────────────────────────────────────────────────────
+
+@router.post("/offer", response_model=SkillResponse, status_code=201)
+async def post_skill_offer(payload: SkillOfferRequest) -> SkillResponse:
+    """
+    Encode the offered skill and store it with its embedding vector.
+    This makes it discoverable by future pgvector similarity searches.
+    """
+    embedding: list[float] = encode_text(payload.title, payload.description)
+    client = get_supabase_client()
+
+    result = (
+        client.table("skills_offered")
+        .insert(
+            {
+                "user_id": payload.user_id,
+                "title": payload.title,
+                "description": payload.description,
+                "embedding": embedding,
+            }
+        )
+        .execute()
+    )
+
+    if not result.data:
+        raise HTTPException(status_code=500, detail="Failed to store skill offer")
+
+    row: dict = result.data[0]
+    return SkillResponse(
+        id=row["id"],
+        user_id=row["user_id"],
+        title=row["title"],
+        description=row["description"] or "",
+    )
+
+
+@router.post("/need", response_model=SkillResponse, status_code=201)
+async def post_skill_need(payload: SkillNeedRequest) -> SkillResponse:
+    """
+    Encode the needed skill, store it, then immediately run the ML matching loop:
+    1. pgvector cosine search against skills_offered
+    2. If best match score > 0.5 → create match + chat session
+    3. Return the new skill row plus match info (if any) so the frontend
+       can redirect the user directly to their chat room.
+    """
+    embedding: list[float] = encode_text(payload.title, payload.description)
+    client = get_supabase_client()
+
+    result = (
+        client.table("skills_needed")
+        .insert(
+            {
+                "user_id": payload.user_id,
+                "title": payload.title,
+                "description": payload.description,
+                "embedding": embedding,
+            }
+        )
+        .execute()
+    )
+
+    if not result.data:
+        raise HTTPException(status_code=500, detail="Failed to store skill need")
+
+    row: dict = result.data[0]
+
+    # ── ML matching loop ─────────────────────────────────────────────────────
+    matches: list[dict] = await find_matches(
+        query_embedding=embedding,
+        exclude_user=payload.user_id,
+        match_count=3,
+    )
+
+    best_match: dict | None = None
+    if matches:
+        best_match = await create_match_if_qualified(
+            teacher_skill=matches[0],
+            learner_skill_id=row["id"],
+            learner_id=payload.user_id,
+        )
+
+    return SkillResponse(
+        id=row["id"],
+        user_id=row["user_id"],
+        title=row["title"],
+        description=row["description"] or "",
+        match=best_match,
+    )

services/ai_coach.py

@@ -0,0 +1,54 @@
+import os
+from typing import AsyncGenerator
+from groq import AsyncGroq
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Initialized once at module level — never per request
+_groq_client: AsyncGroq = AsyncGroq(api_key=os.environ["GROQ_API_KEY"])
+
+_SYSTEM_PROMPT: str = (
+    "You are an AI Coach passively observing a live peer skill-sharing session "
+    "on SkillBridge between a teacher and a learner. You intervene occasionally to:\n"
+    "- Clarify concepts that seem unclear\n"
+    "- Provide concrete, real-world examples\n"
+    "- Suggest free learning resources (YouTube, freeCodeCamp, MDN, Khan Academy, etc.)\n\n"
+    "Keep responses concise (3–5 sentences). Be encouraging and practical. "
+    "Do not repeat what has already been said."
+)
+
+
+def build_coach_prompt(messages: list[dict]) -> list[dict]:
+    """
+    Format the recent chat history into Groq's message list format,
+    prefixed with the AI Coach system prompt.
+    """
+    formatted: list[dict] = [{"role": "system", "content": _SYSTEM_PROMPT}]
+    for msg in messages:
+        sender: str = msg.get("sender_id", "user")
+        content: str = msg.get("content", "")
+        # Coach's own past messages map to 'assistant'; all others to 'user'
+        role: str = "assistant" if sender == "ai_coach" else "user"
+        formatted.append({"role": role, "content": f"[{sender}]: {content}"})
+    return formatted
+
+
+async def get_coach_response(
+    messages: list[dict],
+) -> AsyncGenerator[str, None]:
+    """
+    Stream a Groq LLaMA 3.3 70B response for the AI Coach.
+    Always uses stream=True — never buffers the full response.
+    """
+    prompt = build_coach_prompt(messages)
+    stream = await _groq_client.chat.completions.create(
+        model="llama-3.3-70b-versatile",
+        messages=prompt,
+        stream=True,
+        max_tokens=300,
+    )
+    async for chunk in stream:
+        content: str | None = chunk.choices[0].delta.content
+        if content:
+            yield content

services/embedder.py

@@ -0,0 +1,11 @@
+from sentence_transformers import SentenceTransformer
+
+# Loaded once at module import time — never reloaded per request
+model: SentenceTransformer = SentenceTransformer("all-MiniLM-L6-v2")
+
+
+def encode_text(title: str, description: str = "") -> list[float]:
+    """Encode a skill title + description into a 384-dim normalized vector."""
+    text: str = f"{title} {description}".strip()
+    embedding = model.encode(text, normalize_embeddings=True)
+    return embedding.tolist()

services/matcher.py

@@ -0,0 +1,68 @@
+from db.supabase_client import get_supabase_client
+
+MATCH_THRESHOLD: float = 0.5
+
+
+async def find_matches(
+    query_embedding: list[float],
+    exclude_user: str,
+    match_count: int = 3,
+) -> list[dict]:
+    """
+    Call the pgvector RPC function to find top matching skills_offered rows
+    for a given query embedding. All cosine similarity is computed in SQL.
+    """
+    client = get_supabase_client()
+    result = (
+        client.rpc(
+            "match_skills",
+            {
+                "query_embedding": query_embedding,
+                "exclude_user": exclude_user,
+                "match_count": match_count,
+            },
+        )
+        .execute()
+    )
+    return result.data or []
+
+
+async def create_match_if_qualified(
+    teacher_skill: dict,
+    learner_skill_id: str,
+    learner_id: str,
+) -> dict | None:
+    """
+    Insert a match + chat_session row only when similarity exceeds the threshold.
+    Returns the match dict with an added `chat_session_id` field, or None.
+    """
+    if teacher_skill.get("similarity", 0) <= MATCH_THRESHOLD:
+        return None
+
+    client = get_supabase_client()
+
+    match_result = (
+        client.table("matches")
+        .insert(
+            {
+                "teacher_id": teacher_skill["user_id"],
+                "learner_id": learner_id,
+                "skill_offered_id": teacher_skill["id"],
+                "skill_needed_id": learner_skill_id,
+                "score": teacher_skill["similarity"],
+                "status": "pending",
+            }
+        )
+        .execute()
+    )
+
+    match: dict = match_result.data[0]
+
+    session_result = (
+        client.table("chat_sessions")
+        .insert({"match_id": match["id"]})
+        .execute()
+    )
+
+    match["chat_session_id"] = session_result.data[0]["id"]
+    return match