Feature/pyq solver

.env.example

@@ -13,6 +13,9 @@ SPACES_REGION=nyc3
 SPACES_PUBLIC_URL=https://your_bucket_name.nyc3.cdn.digitaloceanspaces.com
 MAX_OCR_PAGES=12
 MAX_FILE_SIZE_MB=20
+
+# Frontend
+VITE_API_URL=http://127.0.0.1:8001/api
 POSTGRES_USER=user
 POSTGRES_PASSWORD=password
 POSTGRES_DB=pyqdb

backend/alembic/versions/d3dcf6b6fe3f_add_chat_sessions_and_processing_.py

@@ -0,0 +1,46 @@
+"""add chat sessions and processing progress
+
+Revision ID: d3dcf6b6fe3f
+Revises: 9f2c76932a93
+Create Date: 2026-05-17 16:07:40.708352
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'd3dcf6b6fe3f'
+down_revision: Union[str, Sequence[str], None] = '9f2c76932a93'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('chat_sessions',
+    sa.Column('id', sa.UUID(), nullable=False),
+    sa.Column('user_id', sa.UUID(), nullable=False),
+    sa.Column('title', sa.String(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=True),
+    sa.Column('updated_at', sa.DateTime(), nullable=True),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.add_column('questions', sa.Column('session_id', sa.UUID(), nullable=True))
+    op.create_foreign_key('fk_questions_session_id_chat_sessions', 'questions', 'chat_sessions', ['session_id'], ['id'], ondelete='CASCADE')
+    op.add_column('resources', sa.Column('processing_progress', sa.Integer(), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('resources', 'processing_progress')
+    op.drop_constraint('fk_questions_session_id_chat_sessions', 'questions', type_='foreignkey')
+    op.drop_column('questions', 'session_id')
+    op.drop_table('chat_sessions')
+    # ### end Alembic commands ###

backend/app/llm/client.py

@@ -0,0 +1,48 @@
+import json
+import httpx
+from typing import AsyncGenerator
+from ..config import settings
+
+class OpenRouterClient:
+    def __init__(self):
+        self.api_key = settings.OPENROUTER_API_KEY
+        self.base_url = "https://openrouter.ai/api/v1/chat/completions"
+
+    async def stream_chat(self, messages: list, model: str = "openrouter/owl-alpha") -> AsyncGenerator[str, None]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": settings.FRONTEND_URL,
+            "X-Title": "PYQ Solver",
+        }
+
+        payload = {
+            "model": model,
+            "messages": messages,
+            "stream": True
+        }
+
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            async with client.stream("POST", self.base_url, headers=headers, json=payload) as response:
+                if response.status_code != 200:
+                    error_text = await response.aread()
+                    raise RuntimeError(f"OpenRouter Error: {response.status_code} - {error_text.decode()}")
+
+                async for line in response.aiter_lines():
+                    if not line or line == "":
+                        continue
+
+                    if line.startswith("data: "):
+                        data_str = line[6:]
+                        if data_str == "[DONE]":
+                            break
+
+                        try:
+                            data = json.loads(data_str)
+                            chunk = data['choices'][0]['delta'].get('content', "")
+                            if chunk:
+                                yield chunk
+                        except Exception:
+                            continue
+
+open_router_client = OpenRouterClient()

backend/app/llm/prompts.py

@@ -0,0 +1,22 @@
+SOLVER_SYSTEM = """
+You are an expert academic tutor helping a student understand a question from their study materials.
+
+You are given relevant excerpts from the student's own documents as context. 
+Answer the question using ONLY the provided context.
+
+Rules:
+- Be clear, structured, and student-friendly.
+- Use markdown for formatting: headings (###), bold, and bullet points.
+- If the context does not contain enough information to answer the question, say so honestly. Do not make up information.
+- Provide a concise answer first, followed by a more detailed explanation if helpful.
+- Cite the source filename when referencing specific points.
+- DO NOT add information that is not present in the provided context.
+"""
+
+SOLVER_USER_TEMPLATE = """
+Context from student materials:
+{context}
+
+Question:
+{question}
+"""

backend/app/main.py

@@ -1,6 +1,6 @@
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
-from .routers import auth, resources
+from .routers import auth, resources, solver
 from .config import settings
 
 app = FastAPI(title="PYQ Solver API")
@@ -17,6 +17,7 @@
 
 app.include_router(auth.router, prefix="/api")
 app.include_router(resources.router, prefix="/api")
+app.include_router(solver.router, prefix="/api")
 
 @app.get("/")
 async def root():

backend/app/models/__init__.py

@@ -1,5 +1,6 @@
 from .base import Base
 from .user import User
+from .chat_session import ChatSession
 from .resource import Resource
 from .question import Question, question_resources
 from .answer import Answer
@@ -10,6 +11,7 @@
 __all__ = [
     "Base",
     "User",
+    "ChatSession",
     "Resource",
     "Question",
     "question_resources",

backend/app/models/chat_session.py

@@ -0,0 +1,17 @@
+from sqlalchemy import Column, String, DateTime, UUID, ForeignKey
+from sqlalchemy.orm import relationship
+from datetime import datetime
+import uuid
+from .base import Base
+
+class ChatSession(Base):
+    __tablename__ = "chat_sessions"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    title = Column(String, default="New Chat")
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    user = relationship("User", back_populates="chat_sessions")
+    questions = relationship("Question", back_populates="session", cascade="all")

backend/app/models/question.py

@@ -17,10 +17,12 @@ class Question(Base):
 
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    session_id = Column(UUID(as_uuid=True), ForeignKey("chat_sessions.id", ondelete="CASCADE"), nullable=True)
     content = Column(Text, nullable=False)
     delivery_mode = Column(String, nullable=False) # stream | background
     created_at = Column(DateTime, default=datetime.utcnow)
 
     user = relationship("User", back_populates="questions")
+    session = relationship("ChatSession", back_populates="questions")
     resources = relationship("Resource", secondary=question_resources)
     answer = relationship("Answer", back_populates="question", uselist=False, cascade="all, delete-orphan")

backend/app/models/resource.py

@@ -1,4 +1,4 @@
-from sqlalchemy import Column, String, DateTime, UUID, ForeignKey, Text
+from sqlalchemy import Column, String, DateTime, UUID, ForeignKey, Text, Integer
 from sqlalchemy.orm import relationship
 from datetime import datetime
 import uuid
@@ -13,6 +13,7 @@ class Resource(Base):
     file_url = Column(String, nullable=False)
     type = Column(String, nullable=False) # notes | syllabus | past_paper | other
     status = Column(String, default="pending") # pending | processing | ready | failed
+    processing_progress = Column(Integer, default=0)
     extracted_text = Column(Text, nullable=True)
     created_at = Column(DateTime, default=datetime.utcnow)
 

backend/app/models/user.py

@@ -19,3 +19,4 @@ class User(Base):
     questions = relationship("Question", back_populates="user", cascade="all, delete-orphan")
     papers = relationship("Paper", back_populates="user", cascade="all, delete-orphan")
     jobs = relationship("Job", back_populates="user", cascade="all, delete-orphan")
+    chat_sessions = relationship("ChatSession", back_populates="user", cascade="all, delete-orphan")

backend/app/routers/resources.py

@@ -3,10 +3,11 @@
 from sqlalchemy import select
 from typing import List
 import uuid
+import pypdfium2 as pdfium
 from ..database import get_db
 from ..models.user import User
 from ..models.resource import Resource
-from ..schemas.resource import ResourceOut
+from ..schemas.resource import ResourceOut, ResourceUpdate
 from ..routers.auth import get_current_user
 from ..services.storage import storage_service
 from arq import create_pool
@@ -46,6 +47,24 @@ async def upload_resource(
             )
         content.extend(chunk)
 
+    # Page count check for PDFs (User Request)
+    if file.content_type == "application/pdf":
+        try:
+            pdf = pdfium.PdfDocument(bytes(content))
+            num_pages = len(pdf)
+            if num_pages > settings.MAX_OCR_PAGES:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"File has {num_pages} pages. Maximum {settings.MAX_OCR_PAGES} pages allowed for processing."
+                )
+        except HTTPException:
+            raise
+        except Exception as e:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid or corrupted PDF file: {str(e)}"
+            )
+
     # Generate unique filename for storage
     ext = file.filename.split('.')[-1]
     object_name = f"user_{current_user.id}/{uuid.uuid4()}.{ext}"
@@ -127,6 +146,28 @@ async def delete_resource(
 
     return {"message": "Resource deleted successfully"}
 
+@router.patch("/{resource_id}", response_model=ResourceOut)
+async def update_resource(
+    resource_id: uuid.UUID,
+    data: ResourceUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    result = await db.execute(
+        select(Resource).where(Resource.id == resource_id, Resource.user_id == current_user.id)
+    )
+    resource = result.scalar_one_or_none()
+
+    if not resource:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Resource not found")
+
+    if data.filename:
+        resource.filename = data.filename
+
+    await db.commit()
+    await db.refresh(resource)
+    return resource
+
 @router.post("/{resource_id}/retry", response_model=ResourceOut)
 async def retry_extraction(
     resource_id: uuid.UUID,
@@ -160,3 +201,26 @@ async def retry_extraction(
         )
 
     return resource
+
+@router.post("/{resource_id}/stop", response_model=ResourceOut)
+async def stop_processing(
+    resource_id: uuid.UUID,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    result = await db.execute(
+        select(Resource).where(Resource.id == resource_id, Resource.user_id == current_user.id)
+    )
+    resource = result.scalar_one_or_none()
+
+    if not resource:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Resource not found")
+
+    # Mark as failed ONLY if it is still processing.
+    # If it is already 'ready', we don't want to overwrite it.
+    if resource.status == "processing":
+        resource.status = "failed"
+        await db.commit()
+        await db.refresh(resource)
+
+    return resource