Initial commit of SHL Assessment Recommender

.gitignore

@@ -0,0 +1,4 @@
+.env
+.venv/
+__pycache__/
+*.log

Dockerfile

@@ -0,0 +1,25 @@
+# Use an official lightweight Python image
+FROM python:3.10-slim
+
+# Set the working directory
+WORKDIR /code
+
+# Create a non-root user for security
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# Copy requirements first to leverage Docker cache
+COPY --chown=user:user requirements.txt .
+
+# Install dependencies
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+# Copy the rest of the application code
+COPY --chown=user:user . .
+
+# Expose port 7860
+EXPOSE 7860
+
+# Run the FastAPI application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

app/Llm_utils.py

@@ -0,0 +1,28 @@
+import time
+
+
+class UpstreamUnavailableError(Exception):
+    """Raised when the LLM provider fails even after retries (e.g. persistent 503s)."""
+    pass
+
+
+def invoke_with_retry(chain, payload: dict, max_retries: int = 3, base_delay: float = 1.5):
+    """Invokes a langchain chain with exponential backoff on transient failures.
+
+    The Hugging Face router + featherless-ai provider can return a 503 "Service
+    Unavailable" HTML page instead of JSON during cold starts or overload. The
+    OpenAI-compatible client then throws while trying to parse that as a chat
+    completion. Retrying with backoff handles the common transient case instead
+    of failing the whole turn on the first hiccup.
+    """
+    last_error = None
+    for attempt in range(1, max_retries + 1):
+        try:
+            return chain.invoke(payload)
+        except Exception as e:
+            last_error = e
+            is_last = attempt == max_retries
+            print(f"[llm_utils] attempt {attempt}/{max_retries} failed: {e}")
+            if not is_last:
+                time.sleep(base_delay * (2 ** (attempt - 1)))  # 1.5s, 3s, 6s...
+    raise UpstreamUnavailableError(str(last_error)) from last_error

app/Nlu.py

@@ -0,0 +1,82 @@
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import PromptTemplate
+from langchain_core.output_parsers import JsonOutputParser
+from app.schemas import ConversationState
+from app.config import HUGGINGFACEHUB_API_TOKEN
+from app.Llm_utils import invoke_with_retry
+
+class NLUStage:
+    """Stage 1: Reads the conversation and extracts structured facts. 
+    Never recommends tests or writes user-facing prose.
+    """
+    def __init__(self):
+        # Using Llama-3.1-8B-Instruct
+        self.llm = ChatOpenAI(
+            model="meta-llama/Llama-3.1-8B-Instruct:novita",
+            api_key=HUGGINGFACEHUB_API_TOKEN,
+            base_url="https://router.huggingface.co/v1",
+            max_tokens=500,
+            temperature=0.0,
+        )
+        self.parser = JsonOutputParser(pydantic_object=ConversationState)
+        self.prompt = PromptTemplate(
+            template="""You read a conversation between a user and an SHL assessment consultant and extract facts. You do NOT answer the user, recommend tests, or write any reply.
+
+SCOPE CHECK: set "in_scope" to false ONLY if the Latest User Message is completely unrelated to business, hiring, job roles, or SHL assessments. Vague statements like "We need a solution for senior leadership" ARE in-scope.
+
+INTENT — pick exactly one:
+- "new_request": describes a hiring need not yet discussed in this conversation.
+- "clarifying_answer": answers a question the consultant just asked.
+- "comparison_question": asks to compare or explain the difference between named tests.
+- "confirmation": says an existing shortlist/answer is right and they're satisfied.
+- "addition_removal": asks to add, drop, or swap a specific skill or test.
+- "pushback_feedback": says the consultant's last reply was wrong, OR asks regulatory/legal compliance questions about a test's legality.
+- "off_topic": completely unrelated to business/hiring.
+
+Extract from the FULL conversation so far:
+- role_summary: a short phrase describing who this is for, or null if truly unknown.
+- purpose: selection vs. development, or another explicit purpose the user gave, or null if not stated.
+- topic_keywords: list of skills, tech stack, domain, or role-type words useful for a catalog search.
+- compared_tests: test names the user wants compared, else [].
+- ready_to_recommend: true if the user provided BOTH a job role AND at least one specific requirement (skills, traits, industry context, or test type). 
+- CONSULTANT BEHAVIOR: Do not withhold recommendations to get a "perfect" request. If the user provides a role and key attributes (e.g., "Plant Operator, safety-focused"), set this to TRUE immediately. You can always refine the shortlist in the next turn if they give more info. Set this to false ONLY if the request is extremely vague (e.g., "I need a test").
+EXAMPLES OF SUFFICIENT VS INSUFFICIENT INFO:
+
+Latest User Message: "We need a solution for senior leadership."
+{{"in_scope": true, "intent": "new_request", "role_summary": "senior leadership", "purpose": null, "topic_keywords": ["senior leadership"], "compared_tests": [], "ready_to_recommend": false, "missing_info_question": "Happy to help narrow that down. What specific skills or responsibilities are you looking to assess for this leadership pool?"}}
+
+Latest User Message: "Hiring graduate financial analysts — final-year students, no work experience. We need numerical reasoning and a finance knowledge test."
+{{"in_scope": true, "intent": "new_request", "role_summary": "graduate financial analysts", "purpose": "selection", "topic_keywords": ["financial analyst", "numerical reasoning", "finance", "graduate"], "compared_tests": [], "ready_to_recommend": true, "missing_info_question": null}}
+
+Latest User Message: "We're hiring plant operators for a chemical facility. Safety is absolute top priority — reliability, procedure compliance, never cutting corners."
+{{"in_scope": true, "intent": "new_request", "role_summary": "plant operators, chemical facility", "purpose": "selection", "topic_keywords": ["plant operator", "safety", "reliability", "procedure compliance", "manufacturing"], "compared_tests": [], "ready_to_recommend": true, "missing_info_question": null}}
+
+Conversation so far:
+{history}
+
+Latest User Message:
+{input}
+
+Respond with ONLY the JSON object matching this schema, nothing else:
+{format_instructions}""",
+            input_variables=["history", "input"],
+            partial_variables={"format_instructions": self.parser.get_format_instructions()},
+        )
+        self.chain = self.prompt | self.llm | self.parser
+
+    def run(self, history: str, latest_message: str) -> dict:
+        try:
+            return invoke_with_retry(self.chain, {"history": history, "input": latest_message})
+        except Exception as e:
+            print(f"[NLU] Fallback triggered: {e}")
+            # If the API drops completely, force a bypass so the user isn't trapped
+            return {
+                "in_scope": True,
+                "intent": "new_request",
+                "role_summary": "Candidate",
+                "purpose": "selection",
+                "topic_keywords": [w for w in latest_message.replace("'", "").split() if len(w) > 4],
+                "compared_tests": [],
+                "ready_to_recommend": True, 
+                "missing_info_question": None,
+            }

app/Planner.py

@@ -0,0 +1,112 @@
+"""Stage 2 of the pipeline: pure Python decision logic. No LLM call happens here.
+
+This is the core fix for the 'rigid' / hallucinated behavior you were seeing: the
+old single prompt asked a 3B model to *decide* — in the same breath as writing
+prose — whether it had enough info, whether the user was confirming, whether a
+question was a comparison, etc. Small models are unreliable at that kind of
+in-context judgment call. Here, the judgment call is a plain if/else over facts
+the NLU stage already extracted, so it's 100% consistent and free.
+"""
+from typing import List, Dict, Any
+
+
+class Action:
+    def __init__(self, kind: str, **kwargs):
+        self.kind = kind
+        self.__dict__.update(kwargs)
+
+
+def _to_dict(rec) -> dict:
+    if hasattr(rec, "model_dump"):
+        return rec.model_dump()
+    if hasattr(rec, "dict"):
+        return rec.dict()
+    return rec
+
+
+def find_last_recommendations(conversation) -> List[Dict[str, Any]]:
+    """Scans the raw conversation (newest first) for the last Agent turn that
+    carried a non-empty recommendations list. Requires the frontend to echo
+    `recommendations` back on Agent turns (see schemas.Turn / main.py) — this is
+    what lets a 'confirmation' turn reuse the REAL prior shortlist instead of the
+    model having to recall or reconstruct it from plain text."""
+    for turn in reversed(conversation):
+        if turn.role.lower() == "agent" and getattr(turn, "recommendations", None):
+            return [_to_dict(r) for r in turn.recommendations]
+    return []
+
+
+def _last_agent_message(conversation):
+    for turn in reversed(conversation):
+        if turn.role.lower() == "agent":
+            return turn.content.strip()
+    return None
+
+
+def decide(state: dict, conversation) -> Action:
+    if not state.get("in_scope", True):
+        return Action("off_topic")
+
+    intent = state.get("intent", "new_request")
+    prior_recs = find_last_recommendations(conversation)
+
+    if intent == "off_topic":
+        return Action("off_topic")
+
+    if intent == "comparison_question":
+        return Action("compare", compared_tests=state.get("compared_tests", []),
+                       topic_keywords=state.get("compared_tests", []) or state.get("topic_keywords", []))
+
+    if intent == "confirmation":
+        if prior_recs:
+            return Action("close", reuse_recommendations=prior_recs)
+        # Nothing to confirm yet (e.g. "thanks" mid-clarification) — keep going.
+        intent = "new_request"
+
+    if intent == "pushback_feedback":
+        return Action(
+            "redirect",
+            role_summary=state.get("role_summary"),
+            purpose=state.get("purpose"),
+            topic_keywords=state.get("topic_keywords", []),
+            prior_recommendations=prior_recs,
+        )
+
+    # --- Smart Update Detection ---
+    # If we already have prior recommendations, any new requirement is an update to 
+    # the existing list, even if the NLU missed the strict 'addition_removal' intent.
+    updating_flag = False
+    if intent == "addition_removal":
+        updating_flag = True
+    elif intent in ["new_request", "clarifying_answer"] and len(prior_recs) > 0:
+        updating_flag = True
+
+    # --- THE AMNESIA & LOOP FIX ---
+    # If we already have a shortlist from the conversation history, we know we are ready to recommend.
+    # This overrides the NLU if it "forgets" the role summary mid-conversation.
+    if updating_flag and prior_recs:
+        ready = True
+    elif intent == "clarifying_answer":
+        # If the user just gave us more info, stop asking and just recommend!
+        ready = True 
+    else:
+        ready = bool(state.get("ready_to_recommend")) and bool(state.get("role_summary"))
+
+    candidate_question = (
+        state.get("missing_info_question")
+        or "Could you tell me more about the role and the purpose of this assessment?"
+    )
+
+    # LOOP-BREAKER: if the question we're about to ask is the same one already
+    # asked last turn, the NLU stage isn't making progress on it. 
+    # Proceed with whatever is known instead of asking a third time.
+    if not ready:
+        last_agent_msg = _last_agent_message(conversation)
+        if last_agent_msg and candidate_question.strip().lower() == last_agent_msg.strip().lower():
+            ready = bool(state.get("role_summary"))  # proceed if we at least know who this is for
+
+    if ready:
+        return Action("recommend", updating=updating_flag, prior_recommendations=prior_recs,
+                       topic_keywords=state.get("topic_keywords", []))
+
+    return Action("ask_question", question=candidate_question)

app/Responder.py

@@ -0,0 +1,81 @@
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import PromptTemplate
+from langchain_core.output_parsers import JsonOutputParser
+from app.schemas import ChatResponse
+from app.config import HUGGINGFACEHUB_API_TOKEN
+from app.Llm_utils import invoke_with_retry, UpstreamUnavailableError
+
+class ResponderStage:
+    """Stage 3: Phraser stage. Uses the specific action kind
+    determined by the deterministic planner, context data, and real catalog
+    candidates to compile a highly contextual response.
+    """
+    def __init__(self):
+        # Upgraded to Llama-3.1-8B-Instruct
+        self.llm = ChatOpenAI(
+            model="meta-llama/Llama-3.1-8B-Instruct:novita",
+            api_key=HUGGINGFACEHUB_API_TOKEN,
+            base_url="https://router.huggingface.co/v1",
+            max_tokens=700,
+            temperature=0.2,
+        )
+        self.parser = JsonOutputParser(pydantic_object=ChatResponse)
+        self.prompt = PromptTemplate(
+            template="""You are an expert SHL Assessment Consultant writing ONE highly tailored response turn. A planning step has already decided the strategy — your only job is to execute the phrasing naturally based on the catalog data provided below.
+
+Action to perform: {action}
+- "recommend": Present or update an assessment shortlist.
+- "compare": Explicitly explain structural differences between specific tests requested by the user. Do not attach a recommendations array.
+- "redirect": Address user constraints or handle legal/regulatory compliance pushbacks.
+
+Context about the request:
+- Target Audience: {role_summary}
+- Purpose: {purpose}
+- Updating a prior list: {updating}
+- Prior shortlist (if updating/redirecting): {prior_recommendations}
+
+Real catalog candidates available (Choose and discuss ONLY from this list):
+{candidates}
+
+Conversation so far:
+{history}
+
+Latest User Message:
+{input}
+
+CRITICAL LEGAL GUARDRAIL:
+If the Latest User Message asks whether an assessment is legally required, legal obligations under laws like HIPAA, or whether an SHL test legally satisfies a compliance mandate, you MUST explicitly refuse to give legal advice. State clearly that legal compliance and regulatory obligations are outside what you can advise on, and direct them to their legal or compliance team. You can only confirm what the test measures, not its legal sufficiency.
+
+RULES:
+1. Speak like a senior human consultant. Cut out all robotic filler text. Jump straight into the logic and expertise.
+2. Account for catalog constraints explicitly. Call out language limitations if requested tests don't match the requested language.
+3. UPDATING A SHORTLIST: If "Updating a prior list" is True and you have a "Prior shortlist", you MUST physically copy every valid test from the prior shortlist into your new JSON "recommendations" array. Then, ADD the new tests from the candidates list. Do NOT drop the old tests unless requested.
+4. NEVER leak raw JSON arrays, Python dictionaries, or brackets into the "reply" prose.
+5. THE "RECOMMEND + REFINE" STRATEGY: If you are providing a shortlist but feel a specific detail (like seniority, spoken language, or cognitive needs) is missing, provide the preliminary recommendations AND end your text reply by asking the user a specific question to narrow it down further.
+6. Set "end_of_conversation" to false.
+
+Respond with ONLY the JSON object matching this schema:
+{format_instructions}""",
+            input_variables=["action", "role_summary", "purpose", "updating",
+                              "prior_recommendations", "candidates", "history", "input"],
+            partial_variables={"format_instructions": self.parser.get_format_instructions()},
+        )
+        self.chain = self.prompt | self.llm | self.parser
+
+    def run(self, **kwargs) -> dict:
+        try:
+            return invoke_with_retry(self.chain, kwargs)
+        except UpstreamUnavailableError as e:
+            print(f"[Responder] Upstream failure: {e}")
+            return {
+                "reply": "I'm having trouble reaching the assessment engine right now — could you try again in a moment?",
+                "recommendations": [],
+                "end_of_conversation": False,
+            }
+        except Exception as e:
+            print(f"[Responder] Parse failure: {e}")
+            return {
+                "reply": "I ran into an issue formatting that recommendation — could you rephrase your last message?",
+                "recommendations": [],
+                "end_of_conversation": False,
+            }

app/agent.py

@@ -0,0 +1,133 @@
+from app.Nlu import NLUStage
+from app.Planner import decide
+from app.Responder import ResponderStage
+from app.database import db_manager
+
+
+class SHLAgent:
+    """Orchestrates the 3-stage pipeline for one turn:
+
+      1. NLU (LLM)      -> structured facts about the conversation
+      2. Planner (Python) -> deterministic decision of what to do next
+      3. Responder (LLM)  -> phrasing, ONLY when the action needs one
+                              (off_topic / ask_question / close never call the LLM
+                               at all, so they can never hallucinate)
+
+    Recommendations returned by the Responder are validated against the actual
+    retrieved catalog candidates before being returned to the API layer — any
+    name/url the model invents that isn't in the candidate set is dropped.
+    """
+
+    def __init__(self):
+        self.nlu = NLUStage()
+        self.responder = ResponderStage()
+
+    def handle_conversation(self, conversation: list) -> dict:
+        latest = conversation[-1].content
+        history_str = "\n".join(f"{t.role.capitalize()}: {t.content}" for t in conversation[:-1])
+
+        state = self.nlu.run(history=history_str, latest_message=latest)
+
+        # If the NLU call failed due to the LLM provider itself being unavailable
+        # (not a real extraction gap), say so honestly instead of asking a
+        # clarifying question the user already answered.
+        if state.get("_upstream_failure"):
+            return {
+                "reply": "I'm having trouble reaching the assessment engine right now — could you try again in a moment?",
+                "recommendations": [],
+                "end_of_conversation": False,
+            }
+
+        action = decide(state, conversation)
+
+        # --- No-LLM paths: cannot hallucinate by construction ---
+        if action.kind == "off_topic":
+            return {
+                "reply": "I'm focused on helping with SHL assessment recommendations for hiring — happy to help once you've got a role, skill, or candidate pool in mind!",
+                "recommendations": [],
+                "end_of_conversation": False,
+            }
+
+        if action.kind == "ask_question":
+            return {
+                "reply": action.question,
+                "recommendations": [],
+                "end_of_conversation": False,
+            }
+
+        if action.kind == "close":
+            return {
+                "reply": "Great — glad that fits. Locking in this shortlist.",
+                "recommendations": getattr(action, "reuse_recommendations", []),
+                "end_of_conversation": True,
+            }
+
+        # --- LLM path: compare / recommend / redirect, all need retrieval first ---
+        keywords = getattr(action, "topic_keywords", state.get("topic_keywords", []))
+        
+        # FIX: If we are updating an existing list, focus the vector search STRICTLY 
+        # on the newest message so the new test isn't drowned out by old keywords.
+        if getattr(action, "updating", False):
+            query = latest
+        else:
+            query = " ".join(keywords) if keywords else latest
+            
+        candidates = db_manager.query_catalog_structured(query, n_results=8)
+        candidates_str = "\n".join(
+            f"- {c['name']} | {c['test_type']} | {c['url']}" for c in candidates
+        ) or "No close matches found in catalog."
+
+        result = self.responder.run(
+            action=action.kind,  # "compare" | "recommend" | "redirect"
+            role_summary=state.get("role_summary") or "not specified",
+            purpose=state.get("purpose") or "not specified",
+            updating=getattr(action, "updating", False),
+            prior_recommendations=getattr(action, "prior_recommendations", []),
+            candidates=candidates_str,
+            history=history_str,
+            input=latest,
+        )
+
+        # --- Validation ---
+        # Combine the fresh candidates with the prior recommendations to create the allowed whitelist
+        prior_recs = getattr(action, "prior_recommendations", [])
+        allowed_tests = candidates.copy()
+        allowed_urls = {c["url"] for c in allowed_tests}
+        
+        for pr in prior_recs:
+            if isinstance(pr, dict) and pr.get("url") not in allowed_urls:
+                allowed_tests.append(pr)
+                allowed_urls.add(pr["url"])
+
+        # Build validation dictionaries from the combined whitelist
+        valid_by_url = {c["url"]: c for c in allowed_tests}
+        valid_by_name = {c["name"].strip().lower(): c for c in allowed_tests}
+
+        def _resolve(rec):
+            if isinstance(rec, dict):
+                url = rec.get("url")
+                if url in valid_by_url:
+                    return valid_by_url[url]
+                name = (rec.get("name") or "").strip().lower()
+                return valid_by_name.get(name)
+            if isinstance(rec, str):
+                return valid_by_name.get(rec.strip().lower())
+            return None
+
+        resolved = [_resolve(r) for r in result.get("recommendations", [])]
+        
+        # Clean the final list and deduplicate (in case the LLM added a test twice)
+        seen_urls = set()
+        final_recs = []
+        for r in resolved:
+            if r is not None and r["url"] not in seen_urls:
+                final_recs.append(r)
+                seen_urls.add(r["url"])
+
+        result["recommendations"] = final_recs
+        result["end_of_conversation"] = False  # closing only ever happens via the planner's "close" path
+        return result
+
+
+# Global singleton instance
+shl_agent = SHLAgent()

app/config.py

@@ -0,0 +1,10 @@
+import os
+from dotenv import load_dotenv
+
+# Load variables from .env file
+load_dotenv()
+
+HUGGINGFACEHUB_API_TOKEN = os.getenv("HUGGINGFACEHUB_API_TOKEN")
+
+if not HUGGINGFACEHUB_API_TOKEN:
+    raise ValueError("CRITICAL: HUGGINGFACEHUB_API_TOKEN is missing from your environment or .env file.")

app/database.py

@@ -0,0 +1,79 @@
+import json
+import os
+import chromadb
+
+class VectorDBManager:
+    def __init__(self, collection_name: str = "shl_catalog"):
+        # Persistent storage locally, fits stateless server startups perfectly
+        self.client = chromadb.Client()
+        self.collection = self.client.get_or_create_collection(name=collection_name)
+
+    def initialize_catalog(self, catalog_path: str):
+        """Loads and indexes the catalog JSON file if the collection is empty."""
+        if self.collection.count() > 0:
+            return  # Already populated
+
+        if not os.path.exists(catalog_path):
+            raise FileNotFoundError(f"Catalog file not found at: {catalog_path}")
+
+        # Added utf-8 encoding and strict=False to bypass dirty JSON characters
+        with open(catalog_path, "r", encoding="utf-8") as f:
+            catalog = json.load(f, strict=False)
+
+        docs = []
+        metadatas = []
+        ids = []
+
+        for item in catalog:
+            # Combine content for meaningful semantic retrieval
+            text_chunk = (
+                f"Name: {item['name']}. "
+                f"Description: {item['description']}. "
+                f"Job Levels: {', '.join(item.get('job_levels', []))}"
+            )
+            docs.append(text_chunk)
+
+            # Metadata aligns precisely with the output Recommendation model
+            metadatas.append({
+                "name": item["name"],
+                "url": item.get("link", ""),
+                "test_type": item.get("keys", ["General"])[0] if item.get("keys") else "General"
+            })
+            ids.append(str(item["entity_id"]))
+
+        self.collection.add(documents=docs, metadatas=metadatas, ids=ids)
+
+    def query_catalog(self, query_text: str, n_results: int = 8) -> str:
+        """Queries the collection and returns a structured string for prompt context.
+        Kept for backward compatibility — prefer query_catalog_structured for new code,
+        since the structured form is what enables post-generation validation."""
+        results = self.collection.query(query_texts=[query_text], n_results=n_results)
+
+        context_str = ""
+        if results['documents'] and results['documents'][0]:
+            for i, doc in enumerate(results['documents'][0]):
+                meta = results['metadatas'][0][i]
+                context_str += f"- {doc} (URL: {meta['url']}, Type: {meta['test_type']})\n"
+        return context_str
+
+    def query_catalog_structured(self, query_text: str, n_results: int = 8) -> list:
+        """Same query, returned as a list of dicts (name/url/test_type/description)
+        instead of a flattened string. This is the ground truth used both to build
+        the responder's candidate list AND to validate its output afterward —
+        anything the model returns that isn't in this list gets dropped."""
+        results = self.collection.query(query_texts=[query_text], n_results=n_results)
+
+        candidates = []
+        if results['documents'] and results['documents'][0]:
+            for i, doc in enumerate(results['documents'][0]):
+                meta = results['metadatas'][0][i]
+                candidates.append({
+                    "name": meta["name"],
+                    "url": meta["url"],
+                    "test_type": meta["test_type"],
+                    "description": doc,
+                })
+        return candidates
+
+# Global singleton instance
+db_manager = VectorDBManager()

app/main.py

@@ -0,0 +1,154 @@
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from contextlib import asynccontextmanager
+from app.schemas import ChatRequest, ChatResponse
+from app.database import db_manager
+from app.agent import shl_agent
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Setup step executed before the API server accepts traffic
+    catalog_file_path = "shl_product_catalog.json"
+    db_manager.initialize_catalog(catalog_file_path)
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+# --- FRONTEND HTML & JS ---
+html_content = """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>SHL Assessment Recommender</title>
+    <style>
+        body { font-family: Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; background-color: #f4f4f9; }
+        #chat-container { background: white; padding: 20px; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1); height: 500px; overflow-y: auto; margin-bottom: 20px; }
+        .message { margin-bottom: 15px; padding: 10px; border-radius: 5px; }
+        .user { background-color: #e3f2fd; text-align: right; border-left: 4px solid #2196f3; }
+        .agent { background-color: #f1f8e9; text-align: left; border-left: 4px solid #4caf50; }
+        .system { text-align: center; color: #888; font-style: italic; font-size: 0.9em; }
+        table { width: 100%; border-collapse: collapse; margin-top: 10px; font-size: 0.9em; }
+        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
+        th { background-color: #4caf50; color: white; }
+        .input-area { display: flex; gap: 10px; }
+        input[type="text"] { flex-grow: 1; padding: 10px; border: 1px solid #ccc; border-radius: 4px; }
+        button { padding: 10px 20px; background-color: #2196f3; color: white; border: none; border-radius: 4px; cursor: pointer; }
+        button:hover { background-color: #0b7dda; }
+    </style>
+</head>
+<body>
+    <h2>SHL Assessment Consultant</h2>
+    <div id="chat-container">
+        <div class="message system">Start a conversation. E.g., "I'm hiring a Java developer."</div>
+    </div>
+
+    <div class="input-area">
+        <input type="text" id="user-input" placeholder="Type your message here..." onkeypress="if(event.key === 'Enter') sendMessage()">
+        <button onclick="sendMessage()">Send</button>
+    </div>
+
+    <script>
+        // CLIENT-SIDE MEMORY: this array holds the stateless conversation history.
+        // NOTE: Agent turns now also carry `recommendations`, mirroring the
+        // structured list the server returned for that turn. This is required
+        // for confirmation/"that works" turns to reuse the REAL prior shortlist
+        // instead of the model having to recall it from plain text.
+        let conversationHistory = [];
+
+        async function sendMessage() {
+            const inputField = document.getElementById('user-input');
+            const userText = inputField.value.trim();
+            if (!userText) return;
+
+            const chatContainer = document.getElementById('chat-container');
+
+            // 1. Add User Message to UI & History
+            chatContainer.innerHTML += `<div class="message user"><strong>You:</strong> ${userText}</div>`;
+            conversationHistory.push({ "role": "User", "content": userText });
+            inputField.value = '';
+            chatContainer.scrollTop = chatContainer.scrollHeight;
+
+            // 2. Add loading indicator
+            const loadingId = "loading-" + Date.now();
+            chatContainer.innerHTML += `<div id="${loadingId}" class="message system">Consultant is typing...</div>`;
+            chatContainer.scrollTop = chatContainer.scrollHeight;
+
+            try {
+                // 3. Send stateless array to FastAPI backend
+                const response = await fetch('/chat', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ conversation: conversationHistory })
+                });
+
+                const data = await response.json();
+                document.getElementById(loadingId).remove();
+
+                // 4. Format Agent Reply & Recommendations
+                let agentHtml = `<strong>Consultant:</strong> ${data.reply}`;
+
+                if (data.recommendations && data.recommendations.length > 0) {
+                    agentHtml += `<table><tr><th>Test Name</th><th>Type</th><th>Link</th></tr>`;
+                    data.recommendations.forEach(rec => {
+                        agentHtml += `<tr>
+                            <td>${rec.name}</td>
+                            <td>${rec.test_type}</td>
+                            <td><a href="${rec.url}" target="_blank">View</a></td>
+                        </tr>`;
+                    });
+                    agentHtml += `</table>`;
+                }
+
+                // Add Agent Message to UI & History (recommendations included!)
+                chatContainer.innerHTML += `<div class="message agent">${agentHtml}</div>`;
+                conversationHistory.push({
+                    "role": "Agent",
+                    "content": data.reply,
+                    "recommendations": data.recommendations && data.recommendations.length > 0 ? data.recommendations : null
+                });
+
+                // 5. Handle Memory Wipe on Conversation End
+                if (data.end_of_conversation) {
+                    chatContainer.innerHTML += `<div class="message system">--- Conversation Closed. Memory wiped for next session. ---</div>`;
+                    conversationHistory = []; // Wipes the memory instantly
+                }
+
+            } catch (error) {
+                document.getElementById(loadingId).remove();
+                chatContainer.innerHTML += `<div class="message system" style="color: red;">Error connecting to server.</div>`;
+            }
+
+            chatContainer.scrollTop = chatContainer.scrollHeight;
+        }
+    </script>
+</body>
+</html>
+"""
+
+# --- ROUTES ---
+@app.get("/", response_class=HTMLResponse)
+async def get_frontend():
+    # Serves the UI directly at the root URL
+    return html_content
+
+@app.get("/health")
+def health_check():
+    return {"status": "ok"}
+
+@app.post("/chat", response_model=ChatResponse)
+def chat_endpoint(request: ChatRequest):
+    # All orchestration (NLU -> planner -> retrieval -> responder -> validation)
+    # now lives in app.agent.SHLAgent.handle_conversation. The endpoint itself
+    # is just I/O plus a safety net for unexpected pipeline failures.
+    try:
+        response_dict = shl_agent.handle_conversation(request.conversation)
+        return ChatResponse(**response_dict)
+
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        return ChatResponse(
+            reply="I ran into an issue processing that — could you rephrase it?",
+            recommendations=[],
+            end_of_conversation=False
+        )

app/schemas.py

@@ -0,0 +1,51 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+# --- Output Schemas (defined first: Turn needs Recommendation) ---
+class Recommendation(BaseModel):
+    name: str = Field(description="Name of the assessment")
+    url: str = Field(description="The catalog link to the assessment")
+    test_type: str = Field(description="The Test Type from the catalog")
+
+# --- Input Schemas ---
+class Turn(BaseModel):
+    role: str
+    content: str
+    # Optional: the frontend should echo back the recommendations it received on
+    # each Agent turn. This lets the planner ground "confirmation" replies in the
+    # ACTUAL last shortlist shown to the user, instead of asking the LLM to recall
+    # or re-derive it from plain text (which is where hallucination crept in).
+    recommendations: Optional[List[Recommendation]] = None
+
+class ChatRequest(BaseModel):
+    conversation: List[Turn]
+
+class ChatResponse(BaseModel):
+    reply: str = Field(description="The conversational text spoken by the agent")
+    recommendations: List[Recommendation] = Field(
+        description="List of recommended assessments. Empty if asking clarifying questions."
+    )
+    end_of_conversation: bool = Field(description="True if the task is complete, False otherwise")
+
+# --- Internal schema, used only by the NLU stage (not exposed via the API) ---
+class ConversationState(BaseModel):
+    in_scope: bool = Field(
+        description="False only if the latest user message is clearly unrelated to hiring/SHL assessments (e.g. weather, small talk, jokes)."
+    )
+    intent: str = Field(
+        description="One of: new_request, clarifying_answer, comparison_question, confirmation, addition_removal, pushback_feedback, off_topic"
+    )
+    role_summary: Optional[str] = Field(default=None, description="Short description of who the assessment is for")
+    purpose: Optional[str] = Field(default=None, description="Selection vs. development, or other explicit purpose")
+    topic_keywords: List[str] = Field(default_factory=list, description="Skills/domain/role words for catalog search")
+    compared_tests: List[str] = Field(default_factory=list, description="Test names to compare, if intent is comparison_question")
+    missing_info_question: Optional[str] = Field(default=None, description="The single next clarifying question, if not ready to recommend")
+    ready_to_recommend: bool = Field(
+        description=(
+            "True ONLY if there is enough specific detail to pick the right catalog items with confidence — "
+            "this covers role/seniority AND any domain-critical detail that changes which test variant applies "
+            "(e.g. spoken language/accent for contact-centre or call-simulation roles, selection vs. development "
+            "purpose, programming language/stack for technical roles). False if any such detail is still open, "
+            "even if role_summary and purpose both look filled."
+        )
+    )

requirements.txt

@@ -0,0 +1,10 @@
+fastapi
+uvicorn
+pydantic
+python-dotenv
+langchain
+langchain-community
+langchain-huggingface
+langchain-core
+chromadb
+sentence-transformers