Initial commit: AI Consultant Chatbot for HF Spaces

.dockerignore

@@ -0,0 +1,13 @@
+__pycache__
+*.pyc
+*.pyo
+.env
+.git
+.gitignore
+*.db
+test_*.py
+test_*.json
+test_*.txt
+*.md
+.agent/
+.gemini/

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+*.db
+data/sessions.db
+test_*.py
+test_*.json
+test_*.txt
+.agent/
+.gemini/

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install dependencies
+COPY backend/requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy project files
+COPY backend/ ./backend/
+COPY frontend/ ./frontend/
+COPY data/ ./data/ 2>/dev/null || mkdir -p ./data
+
+# HF Spaces runs as user with uid 1000
+RUN useradd -m -u 1000 user
+RUN mkdir -p /app/data && chown -R user:user /app
+USER user
+
+# HF Spaces expects port 7860
+EXPOSE 7860
+
+# Run the FastAPI app from the backend directory
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--app-dir", "backend"]

README.md

@@ -0,0 +1,18 @@
+---
+title: Client Chatbot
+emoji: 💬
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+---
+
+# AI Consultant Chatbot
+
+A domain-agnostic consulting chatbot powered by LangGraph + Groq (Llama 3.3 70B).
+
+## Features
+- Multi-turn diagnostic conversations
+- 5-phase consulting flow (Discovery → Exploration → Constraints → Solution → Refinement)
+- Detailed, actionable final recommendations
+- Session management with SQLite persistence

backend/app.py

@@ -0,0 +1,172 @@
+"""FastAPI application — consultant chatbot microservice.
+
+Endpoints:
+    POST /chat                       — Main chat endpoint
+    GET  /sessions                   — List all sessions
+    POST /sessions/new               — Create a new session
+    GET  /sessions/{session_id}      — Get session details + history
+    DELETE /sessions/{session_id}    — Delete a session
+    GET  /health                     — Health check
+
+The frontend is served as static files from ../frontend/.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from models import (
+    ChatRequest,
+    ChatResponse,
+    Message,
+    NewSessionResponse,
+    Phase,
+    SessionInfo,
+    SessionState,
+)
+from storage import delete_session, init_db, list_sessions, load_session, save_session
+from graph import run_consultation
+
+
+# ---------------------------------------------------------------------------
+# Greeting message — shown at the start of every new session
+# ---------------------------------------------------------------------------
+
+GREETING_MESSAGE = (
+    "**Welcome! I'm your AI consultant.** 👋\n\n"
+    "I help people think through complex problems — whether it's "
+    "**business strategy, product design, technical architecture, operations, "
+    "or anything else.**\n\n"
+    "Here's how our conversation will work:\n"
+    "- You describe your challenge or goal\n"
+    "- I'll ask smart, targeted questions — and share insights along the way\n"
+    "- Together, we'll converge on a clear, actionable solution\n\n"
+    "**So — what's on your mind? What problem are you trying to solve?**"
+)
+
+
+# ---------------------------------------------------------------------------
+# App lifecycle
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await init_db()
+    yield
+
+
+app = FastAPI(
+    title="Consultant Chatbot API",
+    description="Domain-agnostic consulting chatbot powered by LangGraph + Groq",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# CORS — allow all origins for microservice usage
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ---------------------------------------------------------------------------
+# Chat endpoint
+# ---------------------------------------------------------------------------
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat(req: ChatRequest):
+    """Process a user message and return the consultant's response."""
+    # Load or create session
+    session = await load_session(req.session_id)
+    if session is None:
+        session = SessionState(session_id=req.session_id)
+
+    # Run consultation graph
+    result = await run_consultation(session, req.message)
+
+    # Persist updated state
+    await save_session(req.session_id, result["session_state"])
+
+    return ChatResponse(
+        reply=result["assistant_reply"],
+        phase=result["new_phase"],
+        confidence=result["new_confidence"],
+        understanding=result["new_understanding"],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Session management endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/sessions")
+async def get_sessions():
+    """List all active sessions."""
+    sessions = await list_sessions()
+    return {"sessions": sessions}
+
+
+@app.post("/sessions/new")
+async def create_session():
+    """Create a new session with an opening greeting message."""
+    session_id = str(uuid.uuid4())
+    state = SessionState(
+        session_id=session_id,
+        messages=[Message(role="assistant", content=GREETING_MESSAGE)],
+    )
+    await save_session(session_id, state)
+    return {
+        "session_id": session_id,
+        "greeting": GREETING_MESSAGE,
+    }
+
+
+@app.get("/sessions/{session_id}")
+async def get_session(session_id: str):
+    """Get full session details including conversation history."""
+    session = await load_session(session_id)
+    if session is None:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return session.model_dump()
+
+
+@app.delete("/sessions/{session_id}")
+async def remove_session(session_id: str):
+    """Delete a session."""
+    deleted = await delete_session(session_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return {"status": "deleted", "session_id": session_id}
+
+
+# ---------------------------------------------------------------------------
+# Health check
+# ---------------------------------------------------------------------------
+
+@app.get("/health")
+async def health():
+    return {"status": "healthy", "service": "consultant-chatbot"}
+
+
+# ---------------------------------------------------------------------------
+# Serve frontend static files
+# ---------------------------------------------------------------------------
+
+FRONTEND_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "frontend")
+
+if os.path.isdir(FRONTEND_DIR):
+    @app.get("/")
+    async def serve_index():
+        return FileResponse(os.path.join(FRONTEND_DIR, "index.html"))
+
+    app.mount("/static", StaticFiles(directory=FRONTEND_DIR), name="static")

backend/graph.py

@@ -0,0 +1,931 @@
+"""LangGraph-based consultation state machine.
+
+Implements a 5-phase consulting flow controlled by a confidence score.
+
+CODE-LEVEL QUALITY ENFORCEMENT:
+- Simplified question category tracker (3 categories instead of 6)
+- Anti-repetition engine: detects sentence overlap and forces re-generation
+- Anti-hallucination check: verifies claims against conversation history
+- Deferral counter: tracks "I don't know" responses and switches to advice mode
+- Turn-aware instructions: adjusts behavior based on conversation stage
+- Understanding validation: ensures the LLM doesn't fabricate facts
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from difflib import SequenceMatcher
+from typing import Any, TypedDict
+
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from llm import llm
+from models import Message, Phase, SessionState, PHASE_ORDER, PHASE_THRESHOLDS
+from prompts import PHASE_PROMPTS
+
+
+# ---------------------------------------------------------------------------
+# Graph state type
+# ---------------------------------------------------------------------------
+
+class GraphState(TypedDict):
+    session_state: SessionState
+    user_message: str
+    assistant_reply: str
+    new_confidence: float
+    new_understanding: str
+    new_phase: Phase
+
+
+# ---------------------------------------------------------------------------
+# Question Category Tracking System (SIMPLIFIED)
+# ---------------------------------------------------------------------------
+
+# Only 3 broad categories — enough to guide without forcing deep dives
+QUESTION_CATEGORIES = {
+    "business_basics": {
+        "label": "Business Basics",
+        "description": "What they do, what they sell/offer, rough scale",
+        "keywords": ["sell", "product", "service", "business", "store", "shop",
+                     "company", "revenue", "team", "employee", "people",
+                     "industry", "offer", "work", "startup", "project"],
+        "prompt": "You could ask about their business basics — what they do, how big the operation is.",
+    },
+    "problem_details": {
+        "label": "Problem Details",
+        "description": "What exactly is going wrong, since when, how bad",
+        "keywords": ["problem", "issue", "challenge", "slow", "decline",
+                     "month", "year", "since", "affect", "impact",
+                     "drop", "worse", "bad", "struggle", "difficult"],
+        "prompt": "You could ask more about the problem — what exactly is happening, how long, how bad.",
+    },
+    "data_and_attempts": {
+        "label": "Data & Past Attempts",
+        "description": "Where their data lives and what they've tried already",
+        "keywords": ["data", "excel", "spreadsheet", "track", "record",
+                     "tried", "attempt", "before", "already", "didn't work",
+                     "keep", "stored", "written", "noted", "logged"],
+        "prompt": "IMPORTANT: You haven't asked where they keep their data yet. Ask how they track or record their business info (Excel, notebook, software, etc.).",
+    },
+}
+
+
+def _detect_covered_categories(messages: list[Message]) -> dict[str, bool]:
+    """Analyze conversation to determine which question categories have been covered."""
+    covered = {cat: False for cat in QUESTION_CATEGORIES}
+
+    all_text = " ".join(msg.content.lower() for msg in messages)
+
+    for cat_id, cat_info in QUESTION_CATEGORIES.items():
+        keyword_hits = sum(1 for kw in cat_info["keywords"] if kw in all_text)
+        # Need at least 2 keyword hits to consider a category covered
+        if keyword_hits >= 2:
+            covered[cat_id] = True
+
+    return covered
+
+
+def _build_category_guidance(covered: dict[str, bool], turn_number: int) -> str:
+    """Build a SOFT guidance block — suggestions, not demands."""
+    uncovered = [
+        QUESTION_CATEGORIES[cat]["prompt"]
+        for cat, is_covered in covered.items()
+        if not is_covered
+    ]
+
+    if not uncovered:
+        return "\nYou've gathered enough info. Focus on giving RECOMMENDATIONS now.\n"
+
+    # Soft suggestion — max 1 at a time to avoid overwhelming
+    guidance = "\n💡 Suggestion — if relevant, you might want to ask about:\n"
+    guidance += f"  → {uncovered[0]}\n"
+
+    covered_list = [
+        QUESTION_CATEGORIES[cat]["label"]
+        for cat, is_covered in covered.items()
+        if is_covered
+    ]
+    if covered_list:
+        guidance += f"\n🚫 ALREADY COVERED (do NOT ask about these again): {', '.join(covered_list)}\n"
+
+    guidance += "\nBut ONLY ask if it naturally follows from what the client just said. Do NOT force it.\n"
+
+    return guidance
+
+
+# ---------------------------------------------------------------------------
+# Conversation intelligence helpers
+# ---------------------------------------------------------------------------
+
+DEFERRAL_PATTERNS = [
+    r"\bi\s*(?:don'?t|dont|dotn|do\s*not)\s*know\b",
+    r"\bno\s*idea\b",
+    r"\bnot\s*sure\b",
+    r"\byou\s*decide\b",
+    r"\byou\s*tell\s*me\b",
+    r"\bidk\b",
+    r"\bno\s*clue\b",
+    r"\bi\s*have\s*no\s*(idea|clue)\b",
+    r"\bwhat\s*do\s*you\s*(mean|suggest|think|recommend)\b",
+    r"\bcan\s*you\s*explain\b",
+    r"\bnope\b",
+    r"\bi\s*(?:don'?t|dont)\s*(?:really\s*)?know\b",
+]
+
+
+def _count_deferrals(messages: list[Message]) -> int:
+    """Count how many times the user deferred or said 'I don't know'."""
+    count = 0
+    for msg in messages:
+        if msg.role == "user":
+            text = msg.content.lower()
+            for pattern in DEFERRAL_PATTERNS:
+                if re.search(pattern, text):
+                    count += 1
+                    break
+    return count
+
+
+def _count_bot_questions(messages: list[Message]) -> int:
+    """Count total questions the bot has asked across all turns."""
+    return sum(msg.content.count("?") for msg in messages if msg.role == "assistant")
+
+
+def _get_turn_number(messages: list[Message]) -> int:
+    """Get the current turn number (count of user messages)."""
+    return sum(1 for msg in messages if msg.role == "user") + 1
+
+
+def _get_previous_bot_responses(messages: list[Message]) -> list[str]:
+    """Get all previous bot responses."""
+    return [msg.content for msg in messages if msg.role == "assistant"]
+
+
+# Specific patterns that indicate the bot ACTUALLY asked about data STORAGE
+# Must be specific enough to not false-positive on generic mentions
+DATA_STORAGE_QUESTION_PATTERNS = [
+    r"(?:how|where) do you (?:keep track|track|record|store|log|manage)",
+    r"(?:do you|are you) (?:use|using) (?:any |a |)(?:excel|spreadsheet|notebook|software|tool|system|app)",
+    r"(?:excel|spreadsheet|notebook|software|database|app|tool|system).+(?:to track|to record|to manage|to store|to keep)",
+    r"(?:keep|store|record|track|log).+(?:in a |in |on |using |with )(?:excel|spreadsheet|notebook|software|database|app|system|paper)",
+    r"how (?:do you|are you) (?:currently |)(?:tracking|recording|storing|managing|keeping) (?:your |the |all |this )",
+    r"(?:track|record|manage) your (?:business |)(?:information|data|sales|inventory)",
+    r"(?:track or record|record or track|store or track)",
+]
+
+
+def _has_asked_about_data(messages: list[Message]) -> bool:
+    """Check if the bot has SPECIFICALLY asked about data storage/tracking tools.
+    
+    Only returns True if the bot asked WHERE/HOW data is stored (Excel, notebook, etc.)
+    Not just any mention of 'data' or 'track' in general context.
+    """
+    for msg in messages:
+        if msg.role == "assistant" and "?" in msg.content:
+            content_lower = msg.content.lower()
+            # Check each question sentence specifically
+            # Split on ? to get question fragments
+            question_parts = content_lower.split("?")
+            for part in question_parts:
+                for pattern in DATA_STORAGE_QUESTION_PATTERNS:
+                    if re.search(pattern, part):
+                        return True
+    return False
+
+
+def _check_repetition(new_reply: str, previous_replies: list[str]) -> float:
+    """Check sentence-level overlap with previous replies. Returns 0.0-1.0."""
+    if not previous_replies:
+        return 0.0
+
+    new_sentences = set(
+        s.strip().lower()
+        for s in re.split(r'[.!?\n]', new_reply)
+        if len(s.strip()) > 20
+    )
+
+    if not new_sentences:
+        return 0.0
+
+    max_overlap = 0.0
+    for prev in previous_replies:
+        prev_sentences = set(
+            s.strip().lower()
+            for s in re.split(r'[.!?\n]', prev)
+            if len(s.strip()) > 20
+        )
+        if not prev_sentences:
+            continue
+
+        overlap_count = 0
+        for new_s in new_sentences:
+            for prev_s in prev_sentences:
+                if SequenceMatcher(None, new_s, prev_s).ratio() > 0.75:
+                    overlap_count += 1
+                    break
+
+        overlap_ratio = overlap_count / len(new_sentences)
+        max_overlap = max(max_overlap, overlap_ratio)
+
+    return max_overlap
+
+
+# ---------------------------------------------------------------------------
+# Reply quality enforcement (code-level, can't be bypassed by LLM)
+# ---------------------------------------------------------------------------
+
+# Patterns that indicate the bot is asking the client to solve their own problem
+SELF_SOLVING_PATTERNS = [
+    r"what do you think is (?:the |)(?:main |primary |root |)(?:reason|cause|issue)",
+    r"what do you (?:think|believe|feel) (?:is |might be |could be |)",
+    r"how do you think .+ could help",
+    r"what would you (?:like|want|suggest|recommend)",
+    r"do you have any (?:idea|thoughts|theories) (?:on |about |why )",
+    r"why do you think",
+    r"what do you attribute .+ to",
+    r"have you (?:considered|thought about) (?:the role of|how|why|whether)",
+    r"have you (?:considered|thought about) (?:offering|changing|trying|implementing)",
+    # Catch ANY question with "you think" in it
+    r"\?.*you think",
+    r"you think.+\?",
+    r"(?:reason|cause)\s+you\s+think",
+    r"what role (?:do you think |does |)",
+]
+
+# Patterns that suggest causes disguised as questions
+CAUSE_SUGGESTING_PATTERNS = [
+    r"have you noticed any changes in .+(?:demand|market|trend|preference|competition)",
+    r"could (?:it|this) be (?:related to|because of|due to)",
+    r"do you think .+(?:might be|could be) (?:causing|contributing|leading)",
+    r"is it possible that .+(?:demand|pricing|competition|market)",
+    r"(?:the role of|due to) (?:pricing|marketing|product presentation|competition)",
+    r"(?:external factors|market trends|consumer behavior).+(?:impact|affect|contribut)",
+    r"(?:changes in|shifts in) (?:consumer|customer|market|buying) (?:behavior|preference|demand|pattern)",
+    # Listing generic causes
+    r"(?:such as|like|including) (?:low |high |ineffective |poor ).*(?:demand|pric|market|competit)",
+    r"(?:due to|because of) (?:various|several|multiple) factors",
+]
+
+# Filler SENTENCES that should be stripped from ANYWHERE in the response
+# These are full-sentence patterns that add no value and make responses robotic
+FILLER_SENTENCES = [
+    # "I'm glad / I'm happy" openers
+    r"i'm glad you (?:shared|told|mentioned|brought)",
+    r"i'm happy (?:to hear|you shared|you told)",
+    # "I'd love to" filler
+    r"i'd love to (?:learn|help|explore|understand|hear|know|dig)",
+    r"i'd like to (?:learn|help|explore|understand|hear|know|dig)",
+    # Restating the problem robotically
+    r"a slow[- ]moving inventory (?:of|can be)",
+    r"(?:can be|is) a (?:challenging|significant|difficult|tough|particularly challenging) (?:issue|problem|situation|challenge) to (?:tackle|address|deal with)",
+    r"it's likely that this is affecting",
+    r"this (?:can|may|might) (?:be|also be) (?:affecting|impacting|taking)",
+    # Robotic transitions
+    r"it sounds like you(?:'re| are) (?:dealing with|experiencing|having|facing|going through)",
+    r"^it(?:'s| is) (?:clear|evident|apparent|obvious|understandable|interesting) that",
+    r"it can be (?:particularly |especially |quite |very |)(?:challenging|concerning|frustrating|difficult|tough)",
+    r"i (?:can |)(?:understand|see|imagine|appreciate) (?:that |how |why )(?:this|it|you)",
+    r"that(?:'s| is) (?:a |definitely a |certainly a |)(?:great|good|excellent|interesting)",
+    r"thank you for sharing",
+    r"i'm (?:starting to |)(?:get|getting) a sense",
+    r"^(?:a |this is a )(?:challenging|significant|difficult|tough|concerning) (?:situation|challenge|problem|issue)",
+    r"you(?:'d| would) be (?:concerned|worried|frustrated|surprised)",
+    r"it seems like (?:we(?:'ve| have)|you(?:'ve| have))",
+    # Recap openers — bot restates known facts every turn
+    r"you(?:'re| are) (?:in|involved in) the .{3,30} business",
+    r"you(?:'ve| have) (?:been using|mentioned|shared|told|noted|indicated|acknowledged)",
+    r"given the (?:specifics|broad range|unique aspects|diverse nature|complexity)",
+    r"to better understand (?:the scope|your situation|the issue|your)",
+    r"this (?:is a good starting point|indicates you have)",
+    r"i'm excited to learn more",
+    r"i'm looking forward to",
+    r"understanding (?:your|the) specific",
+    r"(?:this|that) (?:can be|is) (?:particularly |especially |)(?:challenging|concerning|frustrating)",
+    # Repeated robotic phrases
+    r"(?:can be |is )particularly (?:challenging|concerning)",
+    r"a (?:challenging|significant) (?:situation|challenge|financial burden)",
+    r"(?:\w+ )?industry(?:,|) where trends and (?:consumer |customer |)preferences can shift",
+    r"wasted resources,? tied-?up capital",
+    r"high value and luxury nature",
+    r"it(?:'s| is) essential to (?:identify|address|tackle|consider)",
+    r"(?:affecting|impacting) your business(?:'s|'s) (?:overall |)(?:performance|cash flow|profitability)",
+    r"(?:overall |)(?:performance|appearance|freshness) and (?:customer engagement|profitability)",
+    r"(?:get|getting) your business back on track",
+    # "I'm imagining" / "I'm thinking"
+    r"i'm (?:imagining|thinking) that (?:this|it) (?:might|may|could|is)",
+    # "It seems like" (broad — catches any usage)
+    r"it seems like (?:the|your|this|that)",
+    # "This could indicate/be due to"
+    r"this (?:could|may|might) (?:indicate|suggest|mean|be due to|be related to|be a sign)",
+    # "It's likely that you're"
+    r"it(?:'s| is) likely that (?:you(?:'re| are)|this|there)",
+    # "Given the high value / slow movement"
+    r"given the (?:high value|slow movement|nature|importance|significance)",
+    # "It's great that you..."
+    r"it(?:'s| is) great that you(?:'ve| have)",
+    # "You've just started our conversation"
+    r"you(?:'ve| have) just started",
+]
+
+# Section headers that create robotic formatting
+RECAP_HEADERS = [
+    r"\*\*(?:key points?|current understanding|summary|what (?:we|i) know(?: so far)?|what you(?:'ve| have) (?:told|shared|mentioned))(?:\s*so far)?\s*:?\*\*",
+    r"\*\*(?:key (?:observations?|takeaways?|insights?|details?|information))\s*:?\*\*",
+    r"\*\*(?:current challenges?|situation overview|current situation)\s*:?\*\*",
+]
+
+
+def _detect_bad_question_patterns(reply: str) -> str | None:
+    """Detect self-solving and cause-suggesting questions.
+    
+    Returns a correction instruction if bad patterns found, None otherwise.
+    """
+    reply_lower = reply.lower()
+    
+    for pattern in SELF_SOLVING_PATTERNS:
+        if re.search(pattern, reply_lower):
+            return (
+                "⚠️ You asked the client to diagnose their own problem. "
+                "YOU are the consultant — YOU figure out the cause. "
+                "Instead, ask a SPECIFIC diagnostic question that helps you "
+                "narrow down the cause yourself. For example, ask about "
+                "specifics of the problem, not what they think is causing it."
+            )
+    
+    for pattern in CAUSE_SUGGESTING_PATTERNS:
+        if re.search(pattern, reply_lower):
+            return (
+                "⚠️ You suggested possible causes IN your question. "
+                "Don't lead the client toward causes you've assumed. "
+                "Ask a NEUTRAL question that lets them describe their "
+                "situation without your bias."
+            )
+    
+    return None
+
+
+def _strip_filler_sentences(reply: str) -> str:
+    """Strip filler sentences from the response.
+    
+    Strategy: Only strip filler from the OPENING of each paragraph.
+    This removes robotic openers while preserving analytical content.
+    If stripping would make the response too short, keep the original.
+    """
+    paragraphs = reply.split("\n")
+    result_paragraphs = []
+    
+    for para in paragraphs:
+        if not para.strip():
+            result_paragraphs.append(para)
+            continue
+        
+        # Split paragraph into sentences
+        sentences = re.split(r'(?<=[.!])\s+', para.strip())
+        if not sentences:
+            result_paragraphs.append(para)
+            continue
+        
+        # Only check the FIRST 2 sentences of each paragraph for filler
+        # This preserves analytical content in the middle/end
+        kept_sentences = list(sentences)  # start with all
+        
+        # Strip leading filler sentences (up to 2)
+        stripped = 0
+        while stripped < min(2, len(kept_sentences)):
+            sent_lower = kept_sentences[0].strip().lower()
+            is_filler = False
+            for pattern in FILLER_SENTENCES:
+                if re.search(pattern, sent_lower):
+                    is_filler = True
+                    break
+            if is_filler:
+                kept_sentences.pop(0)
+                stripped += 1
+            else:
+                break
+        
+        if kept_sentences:
+            rebuilt = " ".join(s.strip() for s in kept_sentences if s.strip())
+            if rebuilt and rebuilt[0].islower():
+                rebuilt = rebuilt[0].upper() + rebuilt[1:]
+            result_paragraphs.append(rebuilt)
+    
+    result = "\n".join(result_paragraphs).strip()
+    result = re.sub(r"\n{3,}", "\n\n", result)
+    result = result.strip()
+    
+    # SAFEGUARD: If stripping made the response too short, keep the original
+    # Count non-question content length
+    non_question = re.sub(r'[^\n]*\?[^\n]*', '', result)
+    if len(non_question.strip()) < 80 and len(reply.strip()) > len(result.strip()):
+        return reply
+    
+    return result if result else reply
+
+
+def _break_wall_of_text(reply: str) -> str:
+    """Break long wall-of-text paragraphs into readable chunks.
+    
+    If any paragraph is longer than 400 chars without a newline,
+    split it into sentences and group them into shorter paragraphs.
+    """
+    paragraphs = reply.split("\n\n")
+    result = []
+    
+    for para in paragraphs:
+        if len(para) > 400 and "\n" not in para.strip():
+            # Split into sentences
+            sentences = re.split(r'(?<=[.!?])\s+', para.strip())
+            if len(sentences) <= 2:
+                result.append(para)
+                continue
+            
+            # Group into chunks of 2-3 sentences
+            chunks = []
+            current_chunk = []
+            for sent in sentences:
+                current_chunk.append(sent)
+                if len(current_chunk) >= 2:
+                    chunks.append(" ".join(current_chunk))
+                    current_chunk = []
+            if current_chunk:
+                chunks.append(" ".join(current_chunk))
+            
+            result.append("\n\n".join(chunks))
+        else:
+            result.append(para)
+    
+    return "\n\n".join(result)
+
+
+def _format_questions(reply: str) -> str:
+    """Ensure each question is on its own paragraph with blank lines around it.
+    
+    The frontend renders questions in styled boxes only when they're in their
+    own <p> tag, which requires blank lines around them in the markdown.
+    """
+    lines = reply.split("\n")
+    result = []
+    
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        
+        # Check if this line contains a question mark (likely a question)
+        if "?" in stripped and len(stripped) > 10:
+            # Add blank line before if the previous line isn't blank
+            if result and result[-1].strip():
+                result.append("")
+            result.append(line)
+            # Mark that we need a blank line after
+            # (handled by checking if next non-empty line is also a question)
+            if i + 1 < len(lines) and lines[i + 1].strip():
+                result.append("")
+        else:
+            result.append(line)
+    
+    text = "\n".join(result)
+    # Clean up triple+ blank lines
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+# ---------------------------------------------------------------------------
+# Anti-hallucination checks
+# ---------------------------------------------------------------------------
+
+def _extract_user_text(messages: list[Message]) -> str:
+    """Get all user messages combined as a single text block."""
+    return " ".join(msg.content.lower() for msg in messages if msg.role == "user")
+
+
+def _validate_understanding(understanding: str, messages: list[Message]) -> str:
+    """Validate that the 'understanding' field doesn't contain fabricated facts.
+
+    If the understanding mentions specific numbers, tools, or details not found
+    in any user message, strip it back to a safer version.
+    """
+    if not understanding:
+        return understanding
+
+    user_text = _extract_user_text(messages)
+    if not user_text:
+        return understanding
+
+    # Check for specific numbers in understanding that aren't in user text
+    numbers_in_understanding = re.findall(r'\b\d[\d,.]+\b', understanding)
+    fabricated_numbers = [
+        n for n in numbers_in_understanding
+        if n not in user_text
+    ]
+
+    # If more than half the specific numbers are fabricated, reset understanding
+    if numbers_in_understanding and len(fabricated_numbers) > len(numbers_in_understanding) / 2:
+        # Rebuild understanding from just user messages
+        user_messages = [msg.content for msg in messages if msg.role == "user"]
+        return "Client has said: " + " | ".join(user_messages[-5:])
+
+    return understanding
+
+
+def _check_hallucination(reply: str, messages: list[Message]) -> bool:
+    """Check if the reply contains likely hallucinated specific claims.
+
+    Returns True if hallucination is detected.
+    """
+    user_text = _extract_user_text(messages)
+    if not user_text:
+        return False
+
+    reply_lower = reply.lower()
+
+    # Check for specific dollar/rupee amounts the user never mentioned
+    amounts_in_reply = re.findall(
+        r'(?:₹|rs\.?|inr|\$|usd)\s*[\d,.]+(?:\s*(?:lakh|crore|k|m|million|billion))?',
+        reply_lower
+    )
+    for amount in amounts_in_reply:
+        # Extract just the number part to check
+        num_part = re.findall(r'[\d,.]+', amount)
+        if num_part and not any(n in user_text for n in num_part):
+            return True
+
+    # Check for percentage claims the user never mentioned
+    percentages_in_reply = re.findall(r'\d+(?:\.\d+)?%', reply_lower)
+    for pct in percentages_in_reply:
+        num = pct.replace('%', '')
+        if num not in user_text and pct not in user_text:
+            return True
+
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Core processing
+# ---------------------------------------------------------------------------
+
+def _build_message_list(state: SessionState, user_message: str) -> list:
+    """Build the message list with intelligence injection."""
+    turn_number = _get_turn_number(state.messages)
+    deferral_count = _count_deferrals(state.messages)
+    questions_asked = _count_bot_questions(state.messages)
+    user_msg_lower = user_message.lower().strip()
+
+    # --- SOLUTION SHORTCUT ---
+    # If user says "give me solution" / "tell me what to do" etc., jump to final answer
+    SOLUTION_SHORTCUT_PATTERNS = [
+        r"give me (?:the |a |)(?:solution|answer|recommendation|plan|advice)",
+        r"tell me what to do",
+        r"just (?:give me|tell me|skip to)",
+        r"what (?:should|do) (?:i|we) do",
+        r"(?:skip|jump) (?:to |)(?:the |)(?:solution|answer|recommendation|advice)",
+        r"i (?:just |)(?:want|need) (?:the |a |your |)(?:solution|answer|recommendation|plan|advice)",
+    ]
+    if any(re.search(p, user_msg_lower) for p in SOLUTION_SHORTCUT_PATTERNS):
+        state.phase = Phase.REFINEMENT
+        state.confidence = max(state.confidence, 0.85)
+
+    # --- NEW TOPIC RESET ---
+    # If we're in SOLUTION/REFINEMENT and user mentions a new topic, reset to DISCOVERY
+    END_CONVO_PATTERNS = [
+        r"^no$", r"^nope$", r"^nothing$", r"^that'?s? (?:all|it)$",
+        r"^thanks?$", r"^thank you", r"^bye$", r"^ok$", r"^okay$",
+    ]
+    is_end_of_convo = any(re.search(p, user_msg_lower) for p in END_CONVO_PATTERNS)
+
+    if state.phase in (Phase.SOLUTION, Phase.REFINEMENT) and not is_end_of_convo:
+        # Check if the last bot message had "anything else" — signals end of a topic
+        last_bot_msg = ""
+        for msg in reversed(state.messages):
+            if msg.role == "assistant":
+                last_bot_msg = msg.content.lower()
+                break
+        if "anything else" in last_bot_msg or "other challenges" in last_bot_msg:
+            # User is bringing up a new topic — reset to discovery
+            state.phase = Phase.DISCOVERY
+            state.confidence = 0.1
+            state.topic_start_turn = turn_number  # Reset the topic turn counter
+            # Keep the conversation history but mark the new topic
+            state.understanding = state.understanding + f"\n\n--- NEW TOPIC: {user_message} ---\n" if state.understanding else ""
+
+    # --- HARD PHASE FORCING — guarantee we reach recommendations ---
+    # Use RELATIVE turn count (turns since current topic started)
+    topic_turns = turn_number - state.topic_start_turn
+    current_phase = state.phase
+    current_confidence = state.confidence
+    if topic_turns >= 12 and current_phase != Phase.REFINEMENT:
+        current_phase = Phase.REFINEMENT
+        current_confidence = max(current_confidence, 0.85)
+        state.phase = current_phase
+        state.confidence = current_confidence
+    elif topic_turns >= 10 and current_phase in (Phase.DISCOVERY, Phase.EXPLORATION):
+        current_phase = Phase.SOLUTION
+        current_confidence = max(current_confidence, 0.65)
+        state.phase = current_phase
+        state.confidence = current_confidence
+
+    # --- USE TURN-1 SPECIFIC PROMPT FOR FIRST MESSAGE ---
+    if turn_number <= 1:
+        from prompts import TURN_1_PROMPT
+        phase_prompt = TURN_1_PROMPT
+    else:
+        phase_prompt = PHASE_PROMPTS[current_phase].format(confidence=current_confidence)
+
+    # Add understanding context (validated)
+    if state.understanding:
+        phase_prompt += (
+            f"\n\nCLIENT INFO (for YOUR reference only — do NOT summarize or repeat this back to the client):"
+            f"\n{state.understanding}\n"
+            f"IMPORTANT: Do NOT start your response by restating what you know about the client. "
+            f"Jump STRAIGHT into new insights, analysis, or questions.\n"
+        )
+
+    # --- CONVERSATION STATS ---
+    stats = f"\nTurn {turn_number} | {questions_asked} questions asked so far | {deferral_count} deferrals\n"
+    phase_prompt += stats
+
+    # --- HARD DATA QUESTION ENFORCEMENT ---
+    # If the bot hasn't asked about data storage by turn 2, force it
+    if turn_number >= 2 and not _has_asked_about_data(state.messages):
+        phase_prompt += """
+⚠️ MANDATORY: You have NOT yet asked where the client keeps their business data.
+ONE of your questions MUST be about how they track or record their business
+information. For example: "How do you keep track of all this — in a spreadsheet,
+a notebook, or some software?" This is critical for your recommendations.
+"""
+    elif turn_number > 1:
+        covered = _detect_covered_categories(state.messages)
+        category_guidance = _build_category_guidance(covered, turn_number)
+        phase_prompt += category_guidance
+
+    # --- DYNAMIC BEHAVIORAL OVERRIDES ---
+    if deferral_count >= 2:
+        phase_prompt += """
+⚠️ THE USER SAID "I DON'T KNOW" MULTIPLE TIMES. They cannot answer more questions.
+SWITCH TO ADVICE MODE IMMEDIATELY:
+- STOP asking diagnostic questions. Give at most 1 simple yes/no question.
+- LEAD with YOUR specific recommendations: "Based on what you've told me, here's what I'd suggest..."
+- Make reasonable assumptions and state them.
+- Be SPECIFIC: name tools, methods, steps. No generic advice like "review your pricing".
+- You are the EXPERT — the client is paying YOU to figure it out.
+"""
+
+    # Question count limits only apply during diagnostic phases
+    # In solution/final phases, the prompt itself handles question limits
+    if state.phase in (Phase.DISCOVERY, Phase.EXPLORATION):
+        if questions_asked >= 20:
+            phase_prompt += "\n⚠️ STOP ASKING. Give your recommendation NOW. Zero questions.\n"
+        elif questions_asked >= 14:
+            phase_prompt += "\nYou've asked enough questions. Shift to mostly advice, at most 1 question.\n"
+
+        if turn_number >= 8:
+            phase_prompt += "\n⚠️ Turn 8+. Give CONCRETE recommendations now. Reference details they shared.\n"
+
+    messages = [SystemMessage(content=phase_prompt)]
+
+    # Conversation history (last 20 messages)
+    for msg in state.messages[-20:]:
+        if msg.role == "user":
+            messages.append(HumanMessage(content=msg.content))
+        else:
+            messages.append(SystemMessage(content=f"[Your previous response]: {msg.content}"))
+
+    messages.append(HumanMessage(content=user_message))
+
+    return messages
+
+
+def _parse_llm_output(raw: str) -> dict[str, Any]:
+    """Parse the JSON output from the LLM with robust fallback."""
+    text = raw.strip()
+
+    # Strip markdown code fences
+    json_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if json_match:
+        text = json_match.group(1)
+    else:
+        brace_match = re.search(r"\{.*\}", text, re.DOTALL)
+        if brace_match:
+            text = brace_match.group(0)
+
+    # Attempt 1: direct parse
+    try:
+        data = json.loads(text)
+        return {
+            "reply": str(data.get("reply", text)),
+            "confidence": float(data.get("confidence", 0.1)),
+            "understanding": str(data.get("understanding", "")),
+        }
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    # Attempt 2: sanitise newlines
+    try:
+        sanitised = re.sub(r'(?<=": ")(.*?)(?="[,\s]*\n?\s*"|\"\s*\})',
+                           lambda m: m.group(0).replace('\n', '\\n'),
+                           text, flags=re.DOTALL)
+        data = json.loads(sanitised)
+        return {
+            "reply": str(data.get("reply", text)),
+            "confidence": float(data.get("confidence", 0.1)),
+            "understanding": str(data.get("understanding", "")),
+        }
+    except (json.JSONDecodeError, ValueError, TypeError):
+        pass
+
+    # Attempt 3: regex extraction
+    reply = ""
+    confidence = 0.1
+    understanding = ""
+
+    reply_match = re.search(
+        r'"reply"\s*:\s*"(.*?)"\s*,\s*"(?:confidence|understanding)',
+        text, re.DOTALL,
+    )
+    if reply_match:
+        reply = reply_match.group(1).replace('\\n', '\n').replace('\\"', '"')
+
+    conf_match = re.search(r'"confidence"\s*:\s*([\d.]+)', text)
+    if conf_match:
+        try:
+            confidence = float(conf_match.group(1))
+        except ValueError:
+            pass
+
+    und_match = re.search(
+        r'"understanding"\s*:\s*"(.*?)"\s*\}',
+        text, re.DOTALL,
+    )
+    if und_match:
+        understanding = und_match.group(1).replace('\\n', '\n').replace('\\"', '"')
+
+    if reply:
+        return {"reply": reply, "confidence": confidence, "understanding": understanding}
+
+    # Ultimate fallback
+    fallback = text
+    for pattern in [r'"reply"\s*:\s*"?', r'"confidence"\s*:.*', r'"understanding"\s*:.*', r'[{}]']:
+        fallback = re.sub(pattern, '', fallback, flags=re.DOTALL)
+    fallback = fallback.strip().strip('"').strip(',').strip()
+
+    return {
+        "reply": fallback if fallback else raw.strip(),
+        "confidence": confidence,
+        "understanding": understanding,
+    }
+
+
+def _determine_phase(confidence: float) -> Phase:
+    """Map confidence score to the appropriate consultation phase."""
+    for phase in reversed(PHASE_ORDER):
+        low, _ = PHASE_THRESHOLDS[phase]
+        if confidence >= low:
+            return phase
+    return Phase.DISCOVERY
+
+
+# ---------------------------------------------------------------------------
+# Main graph execution
+# ---------------------------------------------------------------------------
+
+async def run_consultation(session_state: SessionState, user_message: str) -> GraphState:
+    """Run one turn of the consultation with quality enforcement."""
+
+    # 1. Build messages with intelligence injection
+    messages = _build_message_list(session_state, user_message)
+    turn_number = _get_turn_number(session_state.messages)
+
+    # 2. Call LLM
+    response = await llm.ainvoke(messages)
+    parsed = _parse_llm_output(response.content)
+
+    # 3. Anti-repetition check
+    previous_replies = _get_previous_bot_responses(session_state.messages)
+    overlap = _check_repetition(parsed["reply"], previous_replies)
+
+    if overlap > 0.35 and previous_replies:
+        anti_repeat_msg = SystemMessage(content=(
+            "⚠️ YOUR RESPONSE IS TOO SIMILAR TO A PREVIOUS ONE. The user will see "
+            "repeated content. Write something COMPLETELY DIFFERENT:\n"
+            "- Different opening, different observations, different questions\n"
+            "- Share a NEW insight you haven't mentioned\n"
+            "- Ask about a DIFFERENT topic entirely"
+        ))
+        messages.insert(-1, anti_repeat_msg)
+        response = await llm.ainvoke(messages)
+        parsed = _parse_llm_output(response.content)
+
+    # 3.5. HARD question limit enforcement — max 2 questions
+    reply = parsed["reply"]
+    question_count = reply.count("?")
+    if question_count > 2:
+        # Keep only the first 2 questions, remove the rest
+        parts = reply.split("?")
+        if len(parts) > 3:
+            # Keep everything up to and including the 2nd "?"
+            kept = "?".join(parts[:2]) + "?"
+            # Check if there's meaningful non-question content after
+            remaining = "?".join(parts[2:])
+            remaining_lines = remaining.split("\n")
+            non_question_lines = [
+                line for line in remaining_lines
+                if line.strip() and "?" not in line
+            ]
+            if non_question_lines:
+                kept += "\n" + "\n".join(non_question_lines)
+            parsed["reply"] = kept.strip()
+
+    # 3.6. Anti-hallucination check
+    if _check_hallucination(parsed["reply"], session_state.messages):
+        anti_hallucinate_msg = SystemMessage(content=(
+            "⚠️ YOUR RESPONSE CONTAINS SPECIFIC NUMBERS, AMOUNTS, OR PERCENTAGES "
+            "THAT THE CLIENT NEVER MENTIONED. This is hallucination.\n"
+            "REWRITE your response:\n"
+            "- Remove ALL specific numbers/amounts that the client did not explicitly state\n"
+            "- If you need numbers, ASK the client instead of guessing\n"
+            "- Only reference facts the client actually told you"
+        ))
+        messages.insert(-1, anti_hallucinate_msg)
+        response = await llm.ainvoke(messages)
+        parsed = _parse_llm_output(response.content)
+
+    # 3.7. Minimum response length check — replies must be substantive
+    # (Run BEFORE bad question check so expanded responses get checked too)
+    reply_text = parsed["reply"]
+    non_q_lines = [line for line in reply_text.split("\n") if "?" not in line]
+    non_q_content = "\n".join(non_q_lines).strip()
+    if len(non_q_content) < 200:
+        expand_msg = SystemMessage(content=(
+            "⚠️ Your response is TOO SHORT. The client is paying for expert analysis.\n"
+            "EXPAND your response to include:\n"
+            "- 1-2 opening sentences reacting to what they said\n"
+            "- A **bold header** like '**Key Observations**' followed by 3-4 bullet points\n"
+            "  with specific insights, industry knowledge, or patterns you've noticed\n"
+            "- 1-2 sentences of concrete recommendation or context\n"
+            "- THEN your question(s)\n"
+            "Total response before questions should be at least 5-8 sentences."
+        ))
+        messages.insert(-1, expand_msg)
+        response = await llm.ainvoke(messages)
+        parsed = _parse_llm_output(response.content)
+
+    # 3.8. Bad question pattern check (self-solving, cause-suggesting)
+    # Runs AFTER length expansion so expanded responses are also checked
+    correction = _detect_bad_question_patterns(parsed["reply"])
+    if correction:
+        correction_msg = SystemMessage(content=correction)
+        messages.insert(-1, correction_msg)
+        response = await llm.ainvoke(messages)
+        parsed = _parse_llm_output(response.content)
+
+    # 3.9. Strip leading filler sentences (no LLM call)
+    parsed["reply"] = _strip_filler_sentences(parsed["reply"])
+
+    # 3.10. Break wall-of-text responses into readable paragraphs
+    parsed["reply"] = _break_wall_of_text(parsed["reply"])
+
+    # 3.11. Ensure questions are properly formatted for frontend box styling
+    parsed["reply"] = _format_questions(parsed["reply"])
+
+    # 4. Confidence progression
+    MAX_INCREASE = 0.15
+    MIN_INCREASE = 0.06
+    llm_confidence = min(parsed["confidence"], 1.0)
+
+    if llm_confidence > session_state.confidence:
+        new_confidence = session_state.confidence + min(
+            llm_confidence - session_state.confidence, MAX_INCREASE
+        )
+    else:
+        new_confidence = min(session_state.confidence + MIN_INCREASE, 1.0)
+
+    # 5. Route phase
+    new_phase = _determine_phase(new_confidence)
+
+    # Phase forcing — use topic-relative turn count
+    topic_turns = turn_number - session_state.topic_start_turn
+    if topic_turns >= 12:
+        new_phase = Phase.REFINEMENT
+        new_confidence = max(new_confidence, 0.85)
+    elif topic_turns >= 10 and new_phase in (Phase.DISCOVERY, Phase.EXPLORATION):
+        new_phase = Phase.SOLUTION
+        new_confidence = max(new_confidence, 0.65)
+    # 6. Update understanding (with validation)
+    raw_understanding = parsed["understanding"] if parsed["understanding"] else session_state.understanding
+    new_understanding = _validate_understanding(raw_understanding, session_state.messages)
+
+    # 7. Update session state
+    session_state.messages.append(Message(role="user", content=user_message))
+    session_state.messages.append(Message(role="assistant", content=parsed["reply"]))
+    session_state.confidence = new_confidence
+    session_state.phase = new_phase
+    session_state.understanding = new_understanding
+
+    return GraphState(
+        session_state=session_state,
+        user_message=user_message,
+        assistant_reply=parsed["reply"],
+        new_confidence=new_confidence,
+        new_understanding=new_understanding,
+        new_phase=new_phase,
+    )

backend/llm.py

@@ -0,0 +1,29 @@
+"""Groq LLM setup via LangChain."""
+
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+from langchain_groq import ChatGroq
+
+# Load .env from project root
+load_dotenv(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".env"))
+
+_GROQ_API_KEY = os.getenv("GROQ_API_KEY", "")
+
+if not _GROQ_API_KEY or _GROQ_API_KEY == "your_groq_api_key_here":
+    raise RuntimeError(
+        "GROQ_API_KEY is not set. "
+        "Please add your key to the .env file in the project root."
+    )
+
+# Shared LLM instance – llama-3.3-70b-versatile on Groq for speed + quality
+llm = ChatGroq(
+    model="llama-3.3-70b-versatile",
+    api_key=_GROQ_API_KEY,
+    temperature=0.5,
+    max_tokens=2048,
+    request_timeout=30,
+    max_retries=1,
+)

backend/models.py

@@ -0,0 +1,87 @@
+"""Pydantic models for request/response and internal session state."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Consultation phases
+# ---------------------------------------------------------------------------
+
+class Phase(str, Enum):
+    DISCOVERY = "discovery"
+    EXPLORATION = "exploration"
+    CONSTRAINTS = "constraints"
+    SOLUTION = "solution"
+    REFINEMENT = "refinement"
+
+
+PHASE_ORDER: list[Phase] = [
+    Phase.DISCOVERY,
+    Phase.EXPLORATION,
+    Phase.CONSTRAINTS,
+    Phase.SOLUTION,
+    Phase.REFINEMENT,
+]
+
+# Confidence thresholds that trigger phase transitions
+PHASE_THRESHOLDS: dict[Phase, tuple[float, float]] = {
+    Phase.DISCOVERY:    (0.0, 0.20),
+    Phase.EXPLORATION:  (0.20, 0.40),
+    Phase.CONSTRAINTS:  (0.40, 0.60),
+    Phase.SOLUTION:     (0.60, 0.80),
+    Phase.REFINEMENT:   (0.80, 1.00),
+}
+
+
+# ---------------------------------------------------------------------------
+# API models
+# ---------------------------------------------------------------------------
+
+class ChatRequest(BaseModel):
+    session_id: str = Field(..., description="Unique session identifier")
+    message: str = Field(..., min_length=1, description="User message")
+
+
+class ChatResponse(BaseModel):
+    reply: str
+    phase: Phase
+    confidence: float = Field(ge=0.0, le=1.0)
+    understanding: str = Field(default="", description="Extracted understanding so far")
+
+
+class SessionInfo(BaseModel):
+    session_id: str
+    phase: Phase
+    confidence: float
+    message_count: int
+    created_at: str
+    updated_at: str
+
+
+class NewSessionResponse(BaseModel):
+    session_id: str
+
+
+# ---------------------------------------------------------------------------
+# Internal state (persisted in SQLite as JSON)
+# ---------------------------------------------------------------------------
+
+class Message(BaseModel):
+    role: str  # "user" | "assistant"
+    content: str
+
+
+class SessionState(BaseModel):
+    session_id: str = ""
+    messages: list[Message] = Field(default_factory=list)
+    understanding: str = ""
+    confidence: float = 0.0
+    phase: Phase = Phase.DISCOVERY
+    topic_start_turn: int = 0  # Turn when current topic started (for phase forcing)
+    created_at: str = ""
+    updated_at: str = ""

backend/prompts.py

@@ -0,0 +1,281 @@
+"""System prompts for each consultation phase.
+
+DESIGN PRINCIPLES:
+- Keep prompts short — the LLM follows fewer rules better
+- Ground every question in what the CLIENT actually said
+- Never let the bot invent facts the client didn't mention
+- Let the LLM generate questions naturally — no hardcoded examples
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Core persona — short, strict, grounded
+# ---------------------------------------------------------------------------
+
+_PERSONA = """You are an expert business consultant — sharp, insightful, warm.
+
+STRICT RULES (violating ANY of these = failure):
+
+1. GROUNDING — NEVER invent, assume, or state facts the client hasn't told you.
+   If you don't know something, ASK — don't guess.
+
+2. QUESTION PRIORITY — Focus on understanding the PROBLEM first.
+   Before asking about operations, team, or processes, make sure you deeply
+   understand WHAT is going wrong and WHY. Dig into the problem itself — the
+   specifics, the timing, the root cause. Operational details come later.
+
+3. ASK SIMPLE QUESTIONS — Your questions must be easy for a non-technical person
+   to answer. Avoid jargon, technical terms, or metrics they wouldn't know.
+   Base your questions naturally on what the client just told you.
+
+4. NEVER ask the client to solve their own problem. YOU are the consultant —
+   it's YOUR job to diagnose, analyze, and recommend. Don't ask things like
+   "what do you think is causing this?" or "how do you think X could help?"
+
+5. Ask EXACTLY 1-2 questions per response. NEVER more than 2 question marks total.
+
+6. BANNED PHRASES — NEVER use these (instant failure):
+   - "I'm glad you shared" / "I'm glad you told me"
+   - "I'd love to learn more" / "I'd love to help"
+   - "a challenging issue to tackle"
+   - "affecting your business's overall performance"
+   - "get your business back on track"
+   - "I'm thinking that it might be related to"
+   Instead: JUMP STRAIGHT into your insight. Your first sentence should
+   contain specific knowledge or a sharp observation.
+
+7. FORMATTING — Your response MUST be RICH and well-structured:
+   
+   RESPONSE STRUCTURE (follow this every time):
+   a) Start with 1-2 conversational sentences reacting to what they said
+   b) Then a **bold observation header** followed by 3-4 bullet points:
+      - Each bullet should be a specific insight, observation, or piece of
+        context relevant to their situation
+      - Draw on industry knowledge, common patterns, or what they've shared
+      - Be concrete: mention specific approaches, tools, strategies
+   c) Optionally: 1-2 sentences of brief recommendation or industry context
+   d) End with your question(s)
+   
+   Your response BEFORE the questions should be at LEAST 5-8 sentences total.
+   Short replies with just 2-3 sentences are NOT acceptable.
+   
+   QUESTION FORMAT (critical for display):
+   Each question MUST be on its own separate paragraph with a BLANK LINE before it.
+   Example:
+   
+   Your conversational text here...
+   
+   **Key Observations**
+   - Specific insight about their situation
+   - Another observation based on what they shared
+   - Industry context or pattern you've noticed
+   
+   Brief recommendation or context...
+   
+   **Your first question here?**
+   
+   **Your second question here?**
+   
+   NEVER put two questions on the same line or consecutive lines without a blank line.
+   NEVER use headers like "Key Points:", "Current Understanding:", "Summary:".
+
+8. NEVER list generic causes or possibilities. ASK to find out.
+
+9. When user says "I don't know" → stop asking, give your recommendation instead.
+
+10. MOVE ON after user answers — Once the user answers a question, that topic is DONE.
+    Do NOT ask follow-up questions about the SAME thing. For example:
+    - If they said "spreadsheet" → DO NOT ask "what challenges with your spreadsheet?"
+    - If they said "online" → DO NOT ask "how do you sell online?"
+    Instead, move to a COMPLETELY DIFFERENT aspect of their business.
+
+11. NEVER repeat content from previous turns.
+
+12. Each question MUST cover a DIFFERENT aspect of the problem. Never ask two
+    questions about the same topic. Vary across: operations, finances, customers,
+    team, strategy, goals, market, competitors.
+
+13. Be SPECIFIC in advice: name actual methods, steps, approaches. No vague advice.
+"""
+
+_OUTPUT_FORMAT = """
+Respond with ONLY a JSON object:
+{{
+  "reply": "Your markdown response",
+  "confidence": <float 0.0-1.0>,
+  "understanding": "Cumulative summary of ONLY what the client has explicitly stated. Do NOT add interpretations."
+}}
+Confidence: start 0.0, max +0.10/turn. Output ONLY the JSON.
+"""
+
+# ---------------------------------------------------------------------------
+# TURN 1 — first response
+# ---------------------------------------------------------------------------
+
+TURN_1_PROMPT = (
+    _PERSONA
+    + """
+THIS IS THE USER'S VERY FIRST MESSAGE.
+
+YOUR RESPONSE MUST:
+1. Start with a short, warm reaction to what they said (1 sentence)
+2. Ask 2 natural follow-up questions about their situation — one about their
+   business/domain and one about the problem. Keep them simple and conversational.
+
+THAT'S IT. Only 2 questions. Both must be **bolded** and on their own line.
+Do NOT lecture. Do NOT list possible causes. Do NOT assume anything.
+Do NOT create any "Key Points" or "Summary" sections.
+"""
+    + _OUTPUT_FORMAT
+)
+
+# ---------------------------------------------------------------------------
+# Phase prompts — used from turn 2 onwards
+# ---------------------------------------------------------------------------
+
+DISCOVERY_PROMPT = (
+    _PERSONA
+    + """
+PHASE: Discovery | Confidence: {confidence:.0%}
+
+You're still learning about their situation. Your priority is to understand
+the problem deeply before moving to operations or solutions.
+
+Ask about what matters most right now — the problem itself, the context,
+the specifics. Only ask about operational details (team, revenue, processes)
+when they're directly relevant to understanding the problem.
+
+1-2 natural follow-up questions based on what they just told you.
+"""
+    + _OUTPUT_FORMAT
+)
+
+EXPLORATION_PROMPT = (
+    _PERSONA
+    + """
+PHASE: Exploration | Confidence: {confidence:.0%}
+
+You understand the basics. Now dig into the ROOT CAUSE and their DATA.
+
+Two things you MUST learn during exploration:
+1. ROOT CAUSE — Which specific parts are affected, what's changed, what
+   they've already tried. Narrow it down.
+2. DATA — Where do they keep track of their business information? Do they
+   use Excel, a notebook, software, or nothing at all? This is critical
+   because your recommendations depend on what data they have access to.
+
+If you haven't asked about their data yet, make ONE of your questions
+about how they track or record their business information.
+
+Give brief insights where you can. 1-2 questions max.
+"""
+    + _OUTPUT_FORMAT
+)
+
+CONSTRAINTS_PROMPT = (
+    _PERSONA
+    + """
+PHASE: Constraints | Confidence: {confidence:.0%}
+
+SHIFT to primarily ADVISING. You have enough info.
+- State your diagnosis clearly
+- Propose specific solutions with clear steps
+- Reference ONLY details the client actually shared
+- At most 1 question
+
+Be specific and concrete. No vague advice.
+"""
+    + _OUTPUT_FORMAT
+)
+
+SOLUTION_PROMPT = (
+    _PERSONA
+    + """
+PHASE: Solution | Confidence: {confidence:.0%}
+
+You now have enough information to deliver a DETAILED, ACTIONABLE solution.
+
+YOUR RESPONSE MUST INCLUDE:
+
+1. **Problem Summary** — 2-3 sentences summarizing what you've learned about
+   their specific situation (reference details THEY told you).
+
+2. **Root Cause Analysis** — What you believe is causing the problem, based on
+   what they've shared. Be specific, not generic.
+
+3. **Step-by-Step Action Plan** — A NUMBERED list of concrete steps they should
+   take, organized by timeline:
+   - **Immediate (This Week):** 2-3 quick wins they can start today
+   - **Short-Term (Next 2-4 Weeks):** 3-4 tactical changes
+   - **Medium-Term (1-3 Months):** 2-3 strategic initiatives
+   
+   Each step must be SPECIFIC: name actual tools, methods, platforms, strategies.
+   NOT "improve your marketing" but "Create an Instagram business account and
+   post 3-4 high-quality product photos per week with relevant hashtags."
+
+4. **Expected Outcomes** — What results they can expect if they follow the plan.
+
+Keep this response LONG and DETAILED — this is the value they came for.
+At most 1 question to clarify implementation details.
+"""
+    + _OUTPUT_FORMAT
+)
+
+REFINEMENT_PROMPT = (
+    _PERSONA
+    + """
+PHASE: Final | Confidence: {confidence:.0%}
+
+Deliver the COMPLETE, FINAL action plan. This is the most important response
+in the entire conversation — make it worth their time.
+
+YOUR RESPONSE MUST INCLUDE:
+
+1. **Executive Summary** — 3-4 sentences summarizing the problem and your
+   recommended approach. Reference specific details they shared.
+
+2. **Detailed Action Pipeline** — A comprehensive NUMBERED step-by-step plan:
+   
+   **Phase 1: Immediate Actions (This Week)**
+   - Step 1: [Specific action with details]
+   - Step 2: [Specific action with details]
+   - Step 3: [Specific action with details]
+   
+   **Phase 2: Short-Term Strategy (Weeks 2-4)**
+   - Step 4: [Specific action with details]
+   - Step 5: [Specific action with details]
+   
+   **Phase 3: Medium-Term Growth (Month 2-3)**
+   - Step 6: [Specific action with details]
+   - Step 7: [Specific action with details]
+
+3. **Tools & Resources** — Specific tools, platforms, or resources they should
+   use (name actual products, websites, methods).
+
+4. **Expected Results** — What outcomes to expect and rough timelines.
+
+5. **Key Metrics to Track** — 3-4 specific numbers they should monitor to
+   know if the plan is working.
+
+Make this response VERY detailed and thorough. This is the deliverable.
+
+End your response by asking:
+"Is there anything else you'd like help with, or any other challenges you're facing?"
+"""
+    + _OUTPUT_FORMAT
+)
+
+# ---------------------------------------------------------------------------
+# Lookup
+# ---------------------------------------------------------------------------
+
+from models import Phase  # noqa: E402
+
+PHASE_PROMPTS: dict[Phase, str] = {
+    Phase.DISCOVERY: DISCOVERY_PROMPT,
+    Phase.EXPLORATION: EXPLORATION_PROMPT,
+    Phase.CONSTRAINTS: CONSTRAINTS_PROMPT,
+    Phase.SOLUTION: SOLUTION_PROMPT,
+    Phase.REFINEMENT: REFINEMENT_PROMPT,
+}

backend/requirements.txt

@@ -0,0 +1,8 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+langchain-groq==0.2.4
+langchain-core==0.3.51
+langgraph==0.2.60
+pydantic==2.10.0
+aiosqlite==0.20.0
+python-dotenv==1.0.1

backend/storage.py

@@ -0,0 +1,111 @@
+"""SQLite-backed async session storage."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+
+import aiosqlite
+
+from models import Message, Phase, SessionState
+
+DB_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "data")
+DB_PATH = os.path.join(DB_DIR, "sessions.db")
+
+# ---------------------------------------------------------------------------
+# DB initialisation
+# ---------------------------------------------------------------------------
+
+async def init_db() -> None:
+    """Create the sessions table if it doesn't exist."""
+    os.makedirs(DB_DIR, exist_ok=True)
+    async with aiosqlite.connect(DB_PATH) as db:
+        await db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS sessions (
+                session_id  TEXT PRIMARY KEY,
+                state_json  TEXT NOT NULL,
+                created_at  TEXT NOT NULL,
+                updated_at  TEXT NOT NULL
+            )
+            """
+        )
+        await db.commit()
+
+
+# ---------------------------------------------------------------------------
+# CRUD helpers
+# ---------------------------------------------------------------------------
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+async def load_session(session_id: str) -> SessionState | None:
+    """Load a session from the database. Returns None if not found."""
+    async with aiosqlite.connect(DB_PATH) as db:
+        cursor = await db.execute(
+            "SELECT state_json FROM sessions WHERE session_id = ?",
+            (session_id,),
+        )
+        row = await cursor.fetchone()
+        if row is None:
+            return None
+        data = json.loads(row[0])
+        return SessionState(**data)
+
+
+async def save_session(session_id: str, state: SessionState) -> None:
+    """Insert or update a session."""
+    now = _now()
+    state.updated_at = now
+    if not state.created_at:
+        state.created_at = now
+    state_json = state.model_dump_json()
+    async with aiosqlite.connect(DB_PATH) as db:
+        await db.execute(
+            """
+            INSERT INTO sessions (session_id, state_json, created_at, updated_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(session_id)
+            DO UPDATE SET state_json = excluded.state_json,
+                          updated_at = excluded.updated_at
+            """,
+            (session_id, state_json, state.created_at, now),
+        )
+        await db.commit()
+
+
+async def list_sessions() -> list[dict]:
+    """Return lightweight info about all sessions."""
+    async with aiosqlite.connect(DB_PATH) as db:
+        cursor = await db.execute(
+            "SELECT session_id, state_json, created_at, updated_at FROM sessions ORDER BY updated_at DESC"
+        )
+        rows = await cursor.fetchall()
+
+    results = []
+    for sid, sj, ca, ua in rows:
+        data = json.loads(sj)
+        results.append(
+            {
+                "session_id": sid,
+                "phase": data.get("phase", "discovery"),
+                "confidence": data.get("confidence", 0.0),
+                "message_count": len(data.get("messages", [])),
+                "created_at": ca,
+                "updated_at": ua,
+            }
+        )
+    return results
+
+
+async def delete_session(session_id: str) -> bool:
+    """Delete a session. Returns True if it existed."""
+    async with aiosqlite.connect(DB_PATH) as db:
+        cursor = await db.execute(
+            "DELETE FROM sessions WHERE session_id = ?", (session_id,)
+        )
+        await db.commit()
+        return cursor.rowcount > 0

frontend/app.js

@@ -0,0 +1,300 @@
+/* ═══════════════════════════════════════════════════════════════
+   ConsultAI — Chat Client (Vanilla JS)
+   ═══════════════════════════════════════════════════════════════ */
+
+const API_BASE = window.location.origin;
+
+// ─── State ────────────────────────────────────────────────────
+let currentSessionId = null;
+let isWaiting = false;
+
+// ─── DOM refs ─────────────────────────────────────────────────
+const $messages = document.getElementById("messages");
+const $msgContainer = document.getElementById("messagesContainer");
+const $input = document.getElementById("userInput");
+const $btnSend = document.getElementById("btnSend");
+const $btnNewChat = document.getElementById("btnNewChat");
+const $btnToggle = document.getElementById("btnToggleSidebar");
+const $sidebar = document.getElementById("sidebar");
+const $sessionList = document.getElementById("sessionList");
+const $welcomeScreen = document.getElementById("welcomeScreen");
+
+// ─── UUID generator ───────────────────────────────────────────
+function uuid() {
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
+        const r = (Math.random() * 16) | 0;
+        return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+
+// ─── Simple markdown → HTML ───────────────────────────────────
+function renderMarkdown(text) {
+    if (!text) return "";
+    let html = text
+        // Code blocks
+        .replace(/```(\w*)\n([\s\S]*?)```/g, '<pre><code>$2</code></pre>')
+        // Inline code
+        .replace(/`([^`]+)`/g, '<code>$1</code>')
+        // Bold
+        .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+        // Italic
+        .replace(/\*(.+?)\*/g, '<em>$1</em>')
+        // Headers
+        .replace(/^### (.+)$/gm, '<h3>$1</h3>')
+        .replace(/^## (.+)$/gm, '<h2>$1</h2>')
+        .replace(/^# (.+)$/gm, '<h1>$1</h1>')
+        // Blockquote
+        .replace(/^> (.+)$/gm, '<blockquote>$1</blockquote>')
+        // Unordered list items
+        .replace(/^[-*] (.+)$/gm, '<li>$1</li>')
+        // Numbered list items
+        .replace(/^\d+\. (.+)$/gm, '<li>$1</li>');
+
+    // Wrap consecutive <li> in <ul>
+    html = html.replace(/((?:<li>.*<\/li>\n?)+)/g, '<ul>$1</ul>');
+    // Paragraphs (lines not already wrapped in block elements)
+    // Allow <strong> and <em> lines to be wrapped in <p> (they're inline, not block)
+    html = html.replace(/^(?!<[hupbol]|<li|<code|<pre|<block|<ul|<div)(.+)$/gm, '<p>$1</p>');
+    // Clean up extra newlines
+    html = html.replace(/\n{2,}/g, '\n');
+
+    // Highlight questions — wrap <li> or <p> that contain a "?" in a styled box
+    html = html.replace(
+        /<li>(.*?\?)\s*<\/li>/g,
+        '<li class="question-item">$1</li>'
+    );
+    html = html.replace(
+        /<p>(.*?\?)\s*<\/p>/g,
+        '<div class="question-highlight"><span class="question-icon">❓</span><p>$1</p></div>'
+    );
+
+    return html;
+}
+
+
+
+// ─── Add message to chat ──────────────────────────────────────
+function addMessage(role, content) {
+    // Hide welcome
+    if ($welcomeScreen) $welcomeScreen.style.display = "none";
+
+    const div = document.createElement("div");
+    div.className = `message ${role}-message`;
+
+    const avatar = document.createElement("div");
+    avatar.className = "message-avatar";
+    avatar.textContent = role === "user" ? "U" : "◆";
+
+    const bubble = document.createElement("div");
+    bubble.className = "message-bubble";
+    bubble.innerHTML = role === "assistant" ? renderMarkdown(content) : escapeHtml(content);
+
+    div.appendChild(avatar);
+    div.appendChild(bubble);
+    $messages.appendChild(div);
+    scrollToBottom();
+}
+
+function escapeHtml(text) {
+    const d = document.createElement("div");
+    d.textContent = text;
+    return d.innerHTML.replace(/\n/g, "<br>");
+}
+
+function scrollToBottom() {
+    requestAnimationFrame(() => {
+        $msgContainer.scrollTop = $msgContainer.scrollHeight;
+    });
+}
+
+// ─── Typing indicator ─────────────────────────────────────────
+function showTyping() {
+    const div = document.createElement("div");
+    div.className = "typing-indicator";
+    div.id = "typingIndicator";
+    div.innerHTML = `
+        <div class="message-avatar" style="background:var(--accent-gradient);color:white;width:36px;height:36px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:14px;font-weight:700;">◆</div>
+        <div class="typing-dots"><span></span><span></span><span></span></div>
+    `;
+    $messages.appendChild(div);
+    scrollToBottom();
+}
+
+function hideTyping() {
+    const el = document.getElementById("typingIndicator");
+    if (el) el.remove();
+}
+
+// ─── API calls ────────────────────────────────────────────────
+// ─── Create session via API & show greeting ──────────────────
+async function createNewSession() {
+    try {
+        const res = await fetch(`${API_BASE}/sessions/new`, { method: "POST" });
+        const data = await res.json();
+        currentSessionId = data.session_id;
+
+        // Clear and show greeting
+        $messages.innerHTML = "";
+        if ($welcomeScreen) {
+            $messages.appendChild($welcomeScreen);
+            $welcomeScreen.style.display = "none";
+        }
+        addMessage("assistant", data.greeting);
+        loadSessions();
+        return data.session_id;
+    } catch {
+        // Fallback: generate local id
+        currentSessionId = uuid();
+        return currentSessionId;
+    }
+}
+
+async function sendMessage(message) {
+    if (!message.trim() || isWaiting) return;
+
+    // Auto-create session if none
+    if (!currentSessionId) {
+        await createNewSession();
+    }
+
+    addMessage("user", message);
+    $input.value = "";
+    $input.style.height = "auto";
+    $btnSend.disabled = true;
+    isWaiting = true;
+    showTyping();
+
+    try {
+        const res = await fetch(`${API_BASE}/chat`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ session_id: currentSessionId, message }),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(err.detail || `HTTP ${res.status}`);
+        }
+        const data = await res.json();
+        hideTyping();
+        addMessage("assistant", data.reply);
+        loadSessions(); // refresh sidebar
+    } catch (err) {
+        hideTyping();
+        addMessage("assistant", `⚠️ **Error:** ${err.message}\n\nPlease check that the server is running and try again.`);
+    } finally {
+        isWaiting = false;
+        $btnSend.disabled = !$input.value.trim();
+    }
+}
+
+async function loadSessions() {
+    try {
+        const res = await fetch(`${API_BASE}/sessions`);
+        const data = await res.json();
+        renderSessionList(data.sessions || []);
+    } catch { /* server might not be ready */ }
+}
+
+async function loadSessionHistory(sessionId) {
+    try {
+        const res = await fetch(`${API_BASE}/sessions/${sessionId}`);
+        if (!res.ok) return;
+        const data = await res.json();
+
+        // Clear messages
+        $messages.innerHTML = "";
+        if ($welcomeScreen) {
+            $messages.appendChild($welcomeScreen);
+            $welcomeScreen.style.display = "none";
+        }
+
+        // Re-render history
+        (data.messages || []).forEach(m => addMessage(m.role, m.content));
+
+        currentSessionId = sessionId;
+        highlightActiveSession();
+    } catch { /* ignore */ }
+}
+
+async function deleteSessionById(sessionId) {
+    try {
+        await fetch(`${API_BASE}/sessions/${sessionId}`, { method: "DELETE" });
+        if (currentSessionId === sessionId) {
+            currentSessionId = null;
+            $messages.innerHTML = "";
+            if ($welcomeScreen) {
+                $messages.appendChild($welcomeScreen);
+                $welcomeScreen.style.display = "";
+            }
+        }
+        loadSessions();
+    } catch { /* ignore */ }
+}
+
+// ─── Session list rendering ──────────────────────────────────
+function renderSessionList(sessions) {
+    $sessionList.innerHTML = "";
+    sessions.forEach(s => {
+        const div = document.createElement("div");
+        div.className = "session-item" + (s.session_id === currentSessionId ? " active" : "");
+        div.innerHTML = `
+            <span class="session-item-label">Session · ${s.message_count || 0} msgs</span>
+            <button class="session-item-delete" title="Delete">×</button>
+        `;
+        div.querySelector(".session-item-label").addEventListener("click", () => {
+            loadSessionHistory(s.session_id);
+        });
+        div.querySelector(".session-item-delete").addEventListener("click", e => {
+            e.stopPropagation();
+            deleteSessionById(s.session_id);
+        });
+        $sessionList.appendChild(div);
+    });
+}
+
+function highlightActiveSession() {
+    document.querySelectorAll(".session-item").forEach(el => el.classList.remove("active"));
+    // Not trivial to match back — rely on re-render from loadSessions
+}
+
+// ─── New chat ─────────────────────────────────────────────────
+async function startNewChat() {
+    currentSessionId = null;
+    await createNewSession();
+    $input.focus();
+}
+
+// ─── Event listeners ──────────────────────────────────────────
+$btnSend.addEventListener("click", () => sendMessage($input.value));
+
+$input.addEventListener("input", () => {
+    $btnSend.disabled = !$input.value.trim() || isWaiting;
+    // Auto-resize
+    $input.style.height = "auto";
+    $input.style.height = Math.min($input.scrollHeight, 150) + "px";
+});
+
+$input.addEventListener("keydown", e => {
+    if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        sendMessage($input.value);
+    }
+});
+
+$btnNewChat.addEventListener("click", startNewChat);
+
+$btnToggle.addEventListener("click", () => {
+    $sidebar.classList.toggle("hidden");
+});
+
+// Suggestion chips
+document.querySelectorAll(".suggestion-chip").forEach(chip => {
+    chip.addEventListener("click", () => {
+        const msg = chip.getAttribute("data-msg");
+        sendMessage(msg);
+    });
+});
+
+// ─── Init ─────────────────────────────────────────────────────
+loadSessions();
+createNewSession(); // auto-start first session with greeting

frontend/index.html

@@ -0,0 +1,97 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ConsultAI — Intelligent Problem-Solving</title>
+    <meta name="description"
+        content="AI-powered consultant chatbot for structured problem-solving across any domain." />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap"
+        rel="stylesheet" />
+    <link rel="stylesheet" href="/static/style.css" />
+</head>
+
+<body>
+    <!-- Sidebar -->
+    <aside class="sidebar" id="sidebar">
+        <div class="sidebar-header">
+            <div class="logo">
+                <span class="logo-icon">◆</span>
+                <span class="logo-text">ConsultAI</span>
+            </div>
+            <button class="btn-new-chat" id="btnNewChat" title="New Consultation">
+                <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                    <line x1="12" y1="5" x2="12" y2="19" />
+                    <line x1="5" y1="12" x2="19" y2="12" />
+                </svg>
+            </button>
+        </div>
+        <div class="session-list" id="sessionList">
+            <!-- Sessions populated by JS -->
+        </div>
+        <div class="sidebar-footer">
+            <div class="sidebar-footer-text">Powered by Groq + LangGraph</div>
+        </div>
+    </aside>
+
+    <!-- Main chat area -->
+    <main class="main-area">
+        <!-- Top bar -->
+        <header class="topbar">
+            <button class="btn-toggle-sidebar" id="btnToggleSidebar" title="Toggle sidebar">
+                <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                    <line x1="3" y1="6" x2="21" y2="6" />
+                    <line x1="3" y1="12" x2="21" y2="12" />
+                    <line x1="3" y1="18" x2="21" y2="18" />
+                </svg>
+            </button>
+            <div class="topbar-title">ConsultAI</div>
+        </header>
+
+        <!-- Messages -->
+        <div class="messages-container" id="messagesContainer">
+            <div class="messages" id="messages">
+                <!-- Welcome -->
+                <div class="welcome-screen" id="welcomeScreen">
+                    <div class="welcome-icon">◆</div>
+                    <h1>Welcome to ConsultAI</h1>
+                    <p>I'm your AI consultant. Describe any problem or challenge, and I'll guide you through a
+                        structured analysis to find the best solution.</p>
+                    <div class="welcome-suggestions">
+                        <button class="suggestion-chip"
+                            data-msg="I'm building a SaaS product and struggling with user retention after the free trial ends.">SaaS
+                            Retention</button>
+                        <button class="suggestion-chip"
+                            data-msg="Our supply chain has major inefficiencies and we're losing money on logistics.">Supply
+                            Chain</button>
+                        <button class="suggestion-chip"
+                            data-msg="I want to launch an online education platform but I'm not sure about the best approach.">EdTech
+                            Launch</button>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <!-- Input -->
+        <div class="input-area">
+            <div class="input-wrapper">
+                <textarea id="userInput" placeholder="Describe your problem or respond to my questions…" rows="1"
+                    autofocus></textarea>
+                <button class="btn-send" id="btnSend" title="Send message" disabled>
+                    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                        <line x1="22" y1="2" x2="11" y2="13" />
+                        <polygon points="22 2 15 22 11 13 2 9 22 2" />
+                    </svg>
+                </button>
+            </div>
+            <div class="input-hint">Press Enter to send · Shift+Enter for new line</div>
+        </div>
+    </main>
+
+    <script src="/static/app.js"></script>
+</body>
+
+</html>

frontend/style.css

@@ -0,0 +1,691 @@
+/* ═══════════════════════════════════════════════════════════════
+   ConsultAI — Premium Dark-Mode Chat UI
+   ═══════════════════════════════════════════════════════════════ */
+
+/* --- CSS Variables / Design Tokens --- */
+:root {
+    --bg-primary: #0a0e1a;
+    --bg-secondary: #111827;
+    --bg-tertiary: #1a2038;
+    --bg-surface: rgba(255, 255, 255, 0.04);
+    --bg-glass: rgba(255, 255, 255, 0.06);
+    --bg-glass-hover: rgba(255, 255, 255, 0.10);
+
+    --text-primary: #f0f2f5;
+    --text-secondary: #9ca3af;
+    --text-muted: #6b7280;
+
+    --accent-primary: #6366f1;
+    --accent-secondary: #818cf8;
+    --accent-glow: rgba(99, 102, 241, 0.25);
+    --accent-gradient: linear-gradient(135deg, #6366f1 0%, #8b5cf6 50%, #a78bfa 100%);
+
+    --phase-discovery: #3b82f6;
+    --phase-exploration: #8b5cf6;
+    --phase-constraints: #f59e0b;
+    --phase-solution: #10b981;
+    --phase-refinement: #06d6a0;
+
+    --border-color: rgba(255, 255, 255, 0.08);
+    --border-accent: rgba(99, 102, 241, 0.3);
+
+    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
+    --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.4);
+    --shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.5);
+    --shadow-glow: 0 0 20px var(--accent-glow);
+
+    --radius-sm: 8px;
+    --radius-md: 12px;
+    --radius-lg: 16px;
+    --radius-xl: 20px;
+
+    --sidebar-width: 280px;
+    --topbar-height: 60px;
+
+    --font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+    --transition-normal: 250ms cubic-bezier(0.4, 0, 0.2, 1);
+    --transition-slow: 400ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* --- Reset --- */
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+}
+
+html {
+    font-size: 16px;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+    font-family: var(--font-family);
+    background: var(--bg-primary);
+    color: var(--text-primary);
+    display: flex;
+    height: 100vh;
+    overflow: hidden;
+}
+
+/* --- Scrollbar --- */
+::-webkit-scrollbar {
+    width: 6px;
+}
+
+::-webkit-scrollbar-track {
+    background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.12);
+    border-radius: 3px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: rgba(255, 255, 255, 0.2);
+}
+
+/* ═══════════════════════════════════════════════════
+   SIDEBAR
+   ═══════════════════════════════════════════════════ */
+.sidebar {
+    width: var(--sidebar-width);
+    min-width: var(--sidebar-width);
+    background: var(--bg-secondary);
+    border-right: 1px solid var(--border-color);
+    display: flex;
+    flex-direction: column;
+    transition: transform var(--transition-normal), opacity var(--transition-normal);
+    z-index: 100;
+}
+
+.sidebar.hidden {
+    transform: translateX(-100%);
+    position: absolute;
+    height: 100%;
+    opacity: 0;
+    pointer-events: none;
+}
+
+.sidebar-header {
+    padding: 16px 20px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    border-bottom: 1px solid var(--border-color);
+}
+
+.logo {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+
+.logo-icon {
+    font-size: 22px;
+    background: var(--accent-gradient);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+.logo-text {
+    font-size: 18px;
+    font-weight: 700;
+    letter-spacing: -0.02em;
+}
+
+.btn-new-chat {
+    background: var(--bg-glass);
+    border: 1px solid var(--border-color);
+    color: var(--text-primary);
+    border-radius: var(--radius-sm);
+    padding: 8px;
+    cursor: pointer;
+    transition: all var(--transition-fast);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.btn-new-chat:hover {
+    background: var(--accent-primary);
+    border-color: var(--accent-primary);
+    box-shadow: var(--shadow-glow);
+}
+
+.session-list {
+    flex: 1;
+    overflow-y: auto;
+    padding: 8px;
+}
+
+.session-item {
+    padding: 10px 14px;
+    border-radius: var(--radius-sm);
+    cursor: pointer;
+    transition: all var(--transition-fast);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 2px;
+    font-size: 13px;
+    color: var(--text-secondary);
+}
+
+.session-item:hover {
+    background: var(--bg-glass-hover);
+    color: var(--text-primary);
+}
+
+.session-item.active {
+    background: var(--accent-glow);
+    color: var(--text-primary);
+    border: 1px solid var(--border-accent);
+}
+
+.session-item-label {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    flex: 1;
+}
+
+.session-item-delete {
+    opacity: 0;
+    background: none;
+    border: none;
+    color: var(--text-muted);
+    cursor: pointer;
+    padding: 2px 4px;
+    font-size: 16px;
+    line-height: 1;
+    transition: all var(--transition-fast);
+}
+
+.session-item:hover .session-item-delete {
+    opacity: 1;
+}
+
+.session-item-delete:hover {
+    color: #ef4444;
+}
+
+.sidebar-footer {
+    padding: 12px 20px;
+    border-top: 1px solid var(--border-color);
+}
+
+.sidebar-footer-text {
+    font-size: 11px;
+    color: var(--text-muted);
+    text-align: center;
+}
+
+/* ═══════════════════════════════════════════════════
+   MAIN AREA
+   ═══════════════════════════════════════════════════ */
+.main-area {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    position: relative;
+}
+
+/* --- Top Bar --- */
+.topbar {
+    height: var(--topbar-height);
+    padding: 0 20px;
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    border-bottom: 1px solid var(--border-color);
+    background: rgba(10, 14, 26, 0.8);
+    backdrop-filter: blur(12px);
+    -webkit-backdrop-filter: blur(12px);
+    z-index: 10;
+}
+
+.btn-toggle-sidebar {
+    background: none;
+    border: none;
+    color: var(--text-secondary);
+    cursor: pointer;
+    padding: 6px;
+    border-radius: var(--radius-sm);
+    display: flex;
+    transition: all var(--transition-fast);
+}
+
+.btn-toggle-sidebar:hover {
+    background: var(--bg-glass);
+    color: var(--text-primary);
+}
+
+.topbar-title {
+    font-size: 16px;
+    font-weight: 600;
+    color: var(--text-primary);
+    letter-spacing: -0.01em;
+}
+
+/* ═══════════════════════════════════════════════════
+   MESSAGES
+   ═══════════════════════════════════════════════════ */
+.messages-container {
+    flex: 1;
+    overflow-y: auto;
+    scroll-behavior: smooth;
+}
+
+.messages {
+    max-width: 820px;
+    margin: 0 auto;
+    padding: 24px 20px 100px;
+}
+
+/* --- Welcome Screen --- */
+.welcome-screen {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    text-align: center;
+    padding: 80px 20px 40px;
+    animation: fadeInUp 0.6s ease-out;
+}
+
+.welcome-icon {
+    font-size: 48px;
+    background: var(--accent-gradient);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+    margin-bottom: 16px;
+}
+
+.welcome-screen h1 {
+    font-size: 28px;
+    font-weight: 700;
+    margin-bottom: 12px;
+    letter-spacing: -0.02em;
+}
+
+.welcome-screen p {
+    color: var(--text-secondary);
+    font-size: 15px;
+    max-width: 500px;
+    line-height: 1.6;
+    margin-bottom: 32px;
+}
+
+.welcome-suggestions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 10px;
+    justify-content: center;
+}
+
+.suggestion-chip {
+    background: var(--bg-glass);
+    border: 1px solid var(--border-color);
+    color: var(--text-secondary);
+    padding: 10px 18px;
+    border-radius: 100px;
+    font-size: 13px;
+    cursor: pointer;
+    transition: all var(--transition-fast);
+    font-family: var(--font-family);
+}
+
+.suggestion-chip:hover {
+    background: var(--bg-glass-hover);
+    color: var(--text-primary);
+    border-color: var(--border-accent);
+    box-shadow: var(--shadow-glow);
+}
+
+/* --- Message Bubbles --- */
+.message {
+    display: flex;
+    gap: 12px;
+    margin-bottom: 20px;
+    animation: fadeInUp 0.35s ease-out;
+}
+
+.message.user-message {
+    justify-content: flex-end;
+}
+
+.message.assistant-message {
+    justify-content: flex-start;
+}
+
+.message-avatar {
+    width: 36px;
+    height: 36px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 14px;
+    font-weight: 700;
+    flex-shrink: 0;
+    margin-top: 2px;
+}
+
+.assistant-message .message-avatar {
+    background: var(--accent-gradient);
+    color: white;
+    box-shadow: var(--shadow-glow);
+}
+
+.user-message .message-avatar {
+    background: var(--bg-glass);
+    border: 1px solid var(--border-color);
+    color: var(--text-secondary);
+    order: 2;
+}
+
+.message-bubble {
+    max-width: 75%;
+    padding: 14px 18px;
+    border-radius: var(--radius-lg);
+    line-height: 1.65;
+    font-size: 14px;
+}
+
+.user-message .message-bubble {
+    background: var(--accent-primary);
+    color: white;
+    border-bottom-right-radius: 4px;
+}
+
+.assistant-message .message-bubble {
+    background: var(--bg-glass);
+    border: 1px solid var(--border-color);
+    backdrop-filter: blur(8px);
+    -webkit-backdrop-filter: blur(8px);
+    border-bottom-left-radius: 4px;
+}
+
+/* Markdown inside assistant bubbles */
+.message-bubble h1,
+.message-bubble h2,
+.message-bubble h3 {
+    font-size: 15px;
+    font-weight: 600;
+    margin: 12px 0 6px;
+    color: var(--text-primary);
+}
+
+.message-bubble h1:first-child,
+.message-bubble h2:first-child,
+.message-bubble h3:first-child {
+    margin-top: 0;
+}
+
+.message-bubble p {
+    margin: 10px 0;
+}
+
+.message-bubble ul,
+.message-bubble ol {
+    margin: 6px 0;
+    padding-left: 20px;
+}
+
+.message-bubble li {
+    margin: 3px 0;
+}
+
+/* Question highlighting */
+.message-bubble .question-highlight {
+    background: rgba(99, 102, 241, 0.08);
+    border: 1px solid rgba(99, 102, 241, 0.25);
+    border-left: 3px solid var(--accent-primary);
+    border-radius: var(--radius-sm);
+    padding: 10px 14px;
+    margin: 10px 0;
+    display: flex;
+    align-items: flex-start;
+    gap: 10px;
+}
+
+.message-bubble .question-highlight p {
+    margin: 0;
+    color: var(--text-primary);
+    font-weight: 500;
+}
+
+.message-bubble .question-icon {
+    font-size: 16px;
+    flex-shrink: 0;
+    margin-top: 1px;
+}
+
+.message-bubble li.question-item {
+    background: rgba(99, 102, 241, 0.06);
+    border-left: 2px solid var(--accent-primary);
+    padding: 6px 10px;
+    border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+    margin: 6px 0;
+    list-style: none;
+    font-weight: 500;
+}
+
+.message-bubble strong {
+    color: var(--accent-secondary);
+    font-weight: 600;
+}
+
+.message-bubble code {
+    background: rgba(0, 0, 0, 0.3);
+    padding: 2px 6px;
+    border-radius: 4px;
+    font-size: 13px;
+    font-family: 'Fira Code', monospace;
+}
+
+.message-bubble pre {
+    background: rgba(0, 0, 0, 0.3);
+    padding: 12px;
+    border-radius: var(--radius-sm);
+    overflow-x: auto;
+    margin: 8px 0;
+}
+
+.message-bubble pre code {
+    background: none;
+    padding: 0;
+}
+
+.message-bubble blockquote {
+    border-left: 3px solid var(--accent-primary);
+    padding-left: 12px;
+    color: var(--text-secondary);
+    margin: 8px 0;
+}
+
+/* --- Typing Indicator --- */
+.typing-indicator {
+    display: flex;
+    gap: 12px;
+    margin-bottom: 20px;
+    animation: fadeInUp 0.3s ease-out;
+}
+
+.typing-dots {
+    display: flex;
+    gap: 5px;
+    align-items: center;
+    padding: 14px 18px;
+    background: var(--bg-glass);
+    border: 1px solid var(--border-color);
+    border-radius: var(--radius-lg);
+    border-bottom-left-radius: 4px;
+    backdrop-filter: blur(8px);
+}
+
+.typing-dots span {
+    width: 8px;
+    height: 8px;
+    background: var(--text-muted);
+    border-radius: 50%;
+    animation: typingBounce 1.4s infinite;
+}
+
+.typing-dots span:nth-child(2) {
+    animation-delay: 0.15s;
+}
+
+.typing-dots span:nth-child(3) {
+    animation-delay: 0.3s;
+}
+
+/* ═══════════════════════════════════════════════════
+   INPUT AREA
+   ═══════════════════════════════════════════════════ */
+.input-area {
+    padding: 12px 20px 16px;
+    background: linear-gradient(180deg, transparent 0%, var(--bg-primary) 20%);
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    right: 0;
+}
+
+.input-wrapper {
+    max-width: 820px;
+    margin: 0 auto;
+    display: flex;
+    align-items: flex-end;
+    gap: 10px;
+    background: var(--bg-tertiary);
+    border: 1px solid var(--border-color);
+    border-radius: var(--radius-lg);
+    padding: 8px 8px 8px 18px;
+    transition: border-color var(--transition-fast), box-shadow var(--transition-fast);
+}
+
+.input-wrapper:focus-within {
+    border-color: var(--accent-primary);
+    box-shadow: 0 0 0 3px var(--accent-glow);
+}
+
+.input-wrapper textarea {
+    flex: 1;
+    background: none;
+    border: none;
+    color: var(--text-primary);
+    font-family: var(--font-family);
+    font-size: 14px;
+    line-height: 1.5;
+    resize: none;
+    outline: none;
+    max-height: 150px;
+    padding: 6px 0;
+}
+
+.input-wrapper textarea::placeholder {
+    color: var(--text-muted);
+}
+
+.btn-send {
+    background: var(--accent-primary);
+    border: none;
+    color: white;
+    border-radius: var(--radius-sm);
+    padding: 10px;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: all var(--transition-fast);
+    flex-shrink: 0;
+}
+
+.btn-send:hover:not(:disabled) {
+    background: var(--accent-secondary);
+    box-shadow: var(--shadow-glow);
+}
+
+.btn-send:disabled {
+    opacity: 0.3;
+    cursor: default;
+}
+
+.input-hint {
+    text-align: center;
+    font-size: 11px;
+    color: var(--text-muted);
+    margin-top: 6px;
+}
+
+/* ═══════════════════════════════════════════════════
+   ANIMATIONS
+   ═══════════════════════════════════════════════════ */
+@keyframes fadeInUp {
+    from {
+        opacity: 0;
+        transform: translateY(12px);
+    }
+
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+@keyframes typingBounce {
+
+    0%,
+    60%,
+    100% {
+        transform: translateY(0);
+        opacity: 0.4;
+    }
+
+    30% {
+        transform: translateY(-6px);
+        opacity: 1;
+    }
+}
+
+/* ═══════════════════════════════════════════════════
+   RESPONSIVE
+   ═══════════════════════════════════════════════════ */
+@media (max-width: 768px) {
+    .sidebar {
+        position: absolute;
+        height: 100%;
+        z-index: 200;
+        box-shadow: var(--shadow-lg);
+    }
+
+    .sidebar.hidden {
+        transform: translateX(-100%);
+    }
+
+    .confidence-bar-container {
+        display: none;
+    }
+
+    .message-bubble {
+        max-width: 88%;
+    }
+
+    .welcome-screen {
+        padding: 40px 16px 20px;
+    }
+
+    .welcome-screen h1 {
+        font-size: 22px;
+    }
+}