Refactor backend: modularize query workflow and add local model support

.claude/settings.json

@@ -1,16 +1,3 @@
 {
-  "model": "sonnet",
-  "hooks": {
-    "Stop": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "terminal-notifier -title 'Claude Code' -subtitle 'Session Complete' -message \"Finished working in $(basename \"$PWD\")\" -sound default -timeout 10"
-          }
-        ]
-      }
-    ]
-  }
+  "model": "sonnet"
 }

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.pythonProjects": []
+}

ai_chatbot_backend/.env.example

@@ -29,14 +29,21 @@ admin_password=123
 DATA_DIR=data
 
 # LLM Configuration
-# Options: local, remote, mock
+# Options: local, remote, mock, openai
 # local = connects to external vLLM servers (OpenAI-compatible API)
 # remote = use legacy remote API endpoint
 # mock = use mock responses for testing
+# openai = use OpenAI API (requires OPENAI_API_KEY)
 llm_mode=mock
 # URL for remote model API (used when llm_mode=remote)
 remote_model_url=https://tai.berkeley.edu/api/chat
 
+# OpenAI Configuration (used when llm_mode=openai)
+# API key for OpenAI - required when llm_mode=openai
+OPENAI_API_KEY=sk-your-api-key-here
+# Model to use (e.g., gpt-4o, gpt-4o-mini)
+OPENAI_MODEL=gpt-4o
+
 # vLLM Server Configuration (used when llm_mode=local)
 # These settings configure connections to external vLLM servers running OpenAI-compatible APIs
 # The backend server can run on a different machine from the vLLM servers

ai_chatbot_backend/.gitignore

@@ -124,3 +124,6 @@ data/
 exports/
 *.db
 
+audio/*
+# Claude Code settings
+.claude/

ai_chatbot_backend/app/api/routes/completions.py

@@ -1,37 +1,39 @@
 # Consolidated completions router
+import time
 from typing import List
 from app.api.deps import verify_api_token
 from app.core.models.chat_completion import (
     GeneralCompletionParams,
     FileCompletionParams,
     PracticeCompletionParams,
+    PageContentParams,
+    GeneratePagesParams,
     Message,
     ResponseDelta,
     TextToSpeechParams,
     VoiceTranscriptParams,
     AudioTranscript,
 )
-from app.dependencies.model import get_model_engine, get_whisper_engine
-from app.services.rag_retriever import top_k_selector
-from app.services.rag_generation import (
-    format_chat_msg,
-    generate_chat_response
-)
+from app.dependencies.model import get_model_engine, get_whisper_engine, get_engine_for_mode
+from app.services.query import top_k_selector
+from app.services.generation.chat import run_chat_pipeline
+from app.services.generation.tutor import run_tutor_pipeline
+from app.services.generation.message_format import format_chat_msg
+from app.services.request_timer import RequestTimer
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.responses import JSONResponse, StreamingResponse
 from sqlalchemy.orm import Session
 from app.core.dbs.metadata_db import get_metadata_db
 from app.services.file_service import file_service
 from app.services.problem_service import ProblemService
-from app.services.audio_service import audio_to_text, audio_stream_parser
-from app.services.chat_service import (
-    chat_stream_parser,
+from app.services.audio.stt import audio_to_text, audio_stream_parser
+from app.services.audio.tts import (
     format_audio_text_message,
     audio_generator,
     tts_parsor,
     get_speaker_name
 )
-from app.services.memory_synopsis_service import MemorySynopsisService
+from app.services.memory.service import MemorySynopsisService
 
 router = APIRouter()
 
@@ -57,8 +59,27 @@ async def create_completion(
         db: Session = Depends(get_metadata_db),
         _: bool = Depends(verify_api_token)
 ):
-    # Get the pre-initialized pipeline
-    llm_engine = get_model_engine()
+    # Create timer for tracking request latency
+    timer = RequestTimer(request_id=str(time.time_ns()))
+    timer.mark("request_received")
+
+    # Dynamically select LLM mode based on tutor_mode flag
+    from app.config import settings
+    try:
+        llm_mode = settings.get_llm_mode_for_request(params.tutor_mode)
+        print(f"[INFO] Request mode: tutor_mode={params.tutor_mode}, selected LLM: {llm_mode.value}")
+        llm_engine = get_engine_for_mode(llm_mode.value)
+    except Exception as e:
+        # If tutor mode fails and fallback is enabled, use local model
+        if params.tutor_mode and settings.tutor_fallback_enabled:
+            print(f"[WARNING] Failed to initialize {llm_mode.value} for tutor mode: {e}")
+            print(f"[WARNING] Falling back to local model")
+            llm_engine = get_engine_for_mode("local")
+        else:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail=f"LLM service unavailable: {str(e)}"
+            )
     audio_text = None
     if params.audio:
         whisper_engine = get_whisper_engine()
@@ -91,34 +112,74 @@ async def create_completion(
     elif isinstance(params, PracticeCompletionParams):
         problem_content = _get_problem_content(params, db)
 
-    response, reference_list = await generate_chat_response(
-        params.messages,
+    # Dispatch to chat or tutor pipeline
+    pipeline_fn = run_tutor_pipeline if params.tutor_mode else run_chat_pipeline
+    result = await pipeline_fn(
+        messages=params.messages,
         user_focus=getattr(params, 'user_focus', None),
         answer_content=getattr(params, 'answer_content', None),
         problem_content=problem_content,
         stream=params.stream,
         course=params.course_code,
         engine=llm_engine,
         audio_response=params.audio_response,
-        sid=sid
+        sid=sid,
+        timer=timer,
+        audio_text=audio_text,
     )
 
     if params.stream:
-        return StreamingResponse(
-            chat_stream_parser(
-                response,
-                reference_list,
-                params.audio_response,
-                audio_text=audio_text,
-                messages=format_chat_msg(params.messages),
-                engine=llm_engine,
-                old_sid=sid,
-                course_code=params.course_code
-            ),
-            media_type="text/event-stream"
-        )
+        return StreamingResponse(result, media_type="text/event-stream")
     else:
-        return JSONResponse(ResponseDelta(text=response).model_dump_json(exclude_unset=True))
+        return JSONResponse(ResponseDelta(text=result).model_dump_json(exclude_unset=True))
+
+@router.post("/page-content")
+async def generate_page_content(
+        params: PageContentParams,
+        _: bool = Depends(verify_api_token),
+):
+    """Generate content for a single outline page using the local vLLM model."""
+    from app.services.generation.tutor.page_content import run_page_content_pipeline
+
+    try:
+        llm_engine = get_engine_for_mode("local")
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Local LLM service unavailable: {str(e)}"
+        )
+
+    result = run_page_content_pipeline(params, llm_engine)
+    return StreamingResponse(result, media_type="text/event-stream")
+
+
+@router.post("/generate-pages")
+async def generate_pages(
+        params: GeneratePagesParams,
+        _: bool = Depends(verify_api_token),
+):
+    """Combined pipeline: generate outline (OpenAI) + all page contents (local vLLM) in one SSE stream."""
+    from app.services.generation.tutor.generate_pages import run_generate_pages_pipeline
+
+    try:
+        openai_engine = get_engine_for_mode("openai")
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"OpenAI service unavailable: {str(e)}"
+        )
+
+    try:
+        local_engine = get_engine_for_mode("local")
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Local LLM service unavailable: {str(e)}"
+        )
+
+    result = run_generate_pages_pipeline(params, openai_engine, local_engine)
+    return StreamingResponse(result, media_type="text/event-stream")
+
 
 @router.post("/tts")
 async def text_to_speech(

ai_chatbot_backend/app/config.py

@@ -19,6 +19,7 @@ class LLMModeEnum(str, Enum):
     local = "local"
     remote = "remote"
     mock = "mock"
+    openai = "openai"
 
 
 class Settings(BaseSettings):
@@ -37,6 +38,35 @@ class Settings(BaseSettings):
     )
     remote_model_url: str = Field(description="URL for remote model API")
 
+    # OpenAI Configuration (for llm_mode=openai)
+    openai_api_key: Optional[str] = Field(
+        default=None,
+        description="OpenAI API key for OpenAI mode",
+        alias="OPENAI_API_KEY"
+    )
+    openai_model: str = Field(
+        default="gpt-4o",
+        description="OpenAI model to use (e.g., gpt-4o, gpt-4o-mini)",
+        alias="OPENAI_MODEL"
+    )
+
+    # Conditional LLM Mode Configuration
+    tutor_llm_mode: Optional[LLMModeEnum] = Field(
+        default=None,
+        description="LLM mode for tutor modes (TEXT_CHAT_TUTOR, VOICE_TUTOR). Defaults to 'openai' if not set.",
+        alias="TUTOR_LLM_MODE"
+    )
+    regular_llm_mode: Optional[LLMModeEnum] = Field(
+        default=None,
+        description="LLM mode for regular modes (TEXT_CHAT_REG, VOICE_REGULAR). Defaults to 'local' if not set.",
+        alias="REGULAR_LLM_MODE"
+    )
+    tutor_fallback_enabled: bool = Field(
+        default=True,
+        description="Enable fallback to local model if OpenAI fails for tutor mode",
+        alias="TUTOR_FALLBACK_ENABLED"
+    )
+
     # vLLM Server Configuration
     vllm_chat_url: str = Field(
         default="http://localhost:8001/v1",
@@ -153,6 +183,23 @@ def is_development(self) -> bool:
         """Check if running in development environment."""
         return self.environment == EnvironmentEnum.dev
 
+    def get_llm_mode_for_request(self, tutor_mode: bool) -> LLMModeEnum:
+        """
+        Determine the appropriate LLM mode based on tutor_mode flag.
+
+        Args:
+            tutor_mode: If True, returns tutor LLM mode; otherwise regular LLM mode
+
+        Returns:
+            LLMModeEnum for the appropriate model
+        """
+        if tutor_mode:
+            # Tutor modes: prefer tutor_llm_mode, fallback to openai
+            return self.tutor_llm_mode or LLMModeEnum.openai
+        else:
+            # Regular modes: prefer regular_llm_mode, fallback to local
+            return self.regular_llm_mode or LLMModeEnum.local
+
     @property
     def admin_token(self) -> str:
         return self.admin_token