clean initial commit

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,6 @@
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.env

Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+COPY . .
+
+RUN pip install --no-cache-dir -r backend/requirements.txt
+
+EXPOSE 7860
+
+CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,10 @@
+---
+title: Scalar Hackathon Space 1
+emoji: 🌍
+colorFrom: indigo
+colorTo: pink
+sdk: docker
+pinned: false
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

backend/app/__init__.py

@@ -0,0 +1,9 @@
+"""
+AI Interview Preparation - Core Application Package
+"""
+
+from .environment import InterviewEnv
+from .evaluator import Evaluator
+from .agent import InterviewAgent
+
+__all__ = ['InterviewEnv', 'Evaluator', 'InterviewAgent']

backend/app/agent.py

@@ -0,0 +1,334 @@
+"""
+AI Agent with Retry and Memory Capabilities
+Uses HuggingFace LLM via OpenAI-compatible API
+
+Features:
+- Real LLM integration (HuggingFace Qwen model)
+- Retry mechanism with feedback integration
+- Memory of previous attempts
+- Mock fallback when API unavailable
+"""
+
+import os
+from typing import List, Dict, Any, Optional
+
+
+class InterviewAgent:
+    """
+    AI Agent for Interview Preparation
+    
+    Simulates a candidate that:
+    1. Generates answers to questions
+    2. Receives feedback on answers
+    3. Improves answers using feedback
+    4. Tracks performance over time
+    
+    The agent can use:
+    - Mock/simulated answers (for testing)
+    - Real LLM API (GPT-4, Claude, etc.)
+    """
+    
+    def __init__(self, mode: str = "mock", api_key: str = None, model: str = None):
+        """
+        Initialize the AI agent
+        
+        Args:
+            mode: "mock" for simulated answers or "api" for real LLM
+            api_key: API key for HuggingFace (or from HF_TOKEN env variable)
+            model: Model name (or from MODEL_NAME env variable)
+        """
+        self.mode = mode
+        self.api_key = api_key or os.getenv("HF_TOKEN")
+        self.model = model or os.getenv("MODEL_NAME", "Qwen/Qwen3-Coder-Next:novita")
+        self.base_url = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+        self.memory = []
+        self.current_question_memory = []
+        self.client = None
+        
+        # Initialize API client if using real LLM
+        if mode == "api" and self.api_key:
+            self._init_api_client()
+        elif mode == "api":
+            print("⚠️  API mode selected but no API key provided. Falling back to mock mode.")
+            self.mode = "mock"
+    
+    def _init_api_client(self):
+        """Initialize LLM client via OpenAI-compatible API"""
+        try:
+            from openai import OpenAI
+            self.client = OpenAI(
+                base_url=self.base_url,
+                api_key=self.api_key
+            )
+            print(f"🔌 API client initialized")
+            print(f"   Base URL: {self.base_url}")
+            print(f"   Model: {self.model}")
+        except ImportError:
+            print("⚠️  openai package not installed. Install with: pip install openai")
+            print("⚠️  Falling back to mock mode")
+            self.mode = "mock"
+        except Exception as e:
+            print(f"⚠️  Error initializing API client: {e}")
+            print("⚠️  Falling back to mock mode")
+            self.mode = "mock"
+    
+    def generate_answer(
+        self, 
+        question: str, 
+        feedback: Optional[str] = None,
+        missing_keywords: Optional[List[str]] = None,
+        previous_attempts: Optional[List[Dict]] = None
+    ) -> str:
+        """
+        Generate an answer to the interview question
+        
+        Uses different strategies based on whether this is:
+        - Initial attempt: Generate fresh answer
+        - Retry attempt: Improve using feedback and missing keywords
+        
+        Args:
+            question: The interview question
+            feedback: Feedback from previous attempt (if retry)
+            missing_keywords: Keywords that were missing (if retry)
+            previous_attempts: List of previous attempts (for context)
+            
+        Returns:
+            Generated answer string
+        """
+        if self.mode == "mock":
+            return self._generate_mock_answer(
+                question, 
+                feedback, 
+                missing_keywords,
+                previous_attempts
+            )
+        else:
+            return self._generate_api_answer(
+                question, 
+                feedback, 
+                missing_keywords,
+                previous_attempts
+            )
+    
+    def _generate_mock_answer(
+        self, 
+        question: str, 
+        feedback: Optional[str] = None,
+        missing_keywords: Optional[List[str]] = None,
+        previous_attempts: Optional[List[Dict]] = None
+    ) -> str:
+        """
+        Generate simulated answer (for testing without API costs)
+        
+        Mock Logic:
+        - Initial attempt: Returns partial answer (simulates incomplete knowledge)
+        - Retry attempt: Adds missing keywords to answer (simulates learning)
+        
+        This allows testing the retry/feedback loop without LLM API calls.
+        
+        Args:
+            question: Interview question
+            feedback: Previous feedback
+            missing_keywords: Keywords to add
+            previous_attempts: History
+            
+        Returns:
+            Simulated answer
+        """
+        # Database of mock answers for common topics
+        # These are intentionally partial to trigger retry mechanism
+        mock_knowledge_base = {
+            "binary search": "Binary search is an algorithm that finds items in a sorted array by dividing the search space.",
+            "process": "A process is a program in execution. A thread is a unit of execution within a process.",
+            "normalization": "Database normalization organizes data to reduce redundancy using normal forms.",
+            "oop": "The pillars of OOP include encapsulation and inheritance.",
+            "deadlock": "A deadlock is when processes wait for each other's resources.",
+            "hashmap": "A hashmap stores key-value pairs using a hash function.",
+            "sql": "SQL databases use structured schemas. NoSQL databases are more flexible.",
+            "solid": "SOLID includes Single Responsibility and Open-Closed principles.",
+            "stack": "Stack uses LIFO. Heap is for dynamic allocation.",
+            "rest": "REST is an architectural style for web services using HTTP.",
+            "big o": "Big O notation describes algorithm complexity.",
+            "cap": "CAP theorem states you can only achieve two of three properties in distributed systems."
+        }
+        
+        # Find relevant base answer
+        question_lower = question.lower()
+        base_answer = None
+        
+        for key, answer in mock_knowledge_base.items():
+            if key in question_lower:
+                base_answer = answer
+                break
+        
+        if base_answer is None:
+            base_answer = "This is a complex topic in computer science."
+        
+        # If this is a retry, improve the answer by adding missing keywords
+        if feedback and missing_keywords:
+            improved_answer = base_answer
+            
+            # Add missing keywords to answer (simulating learning)
+            if missing_keywords:
+                improved_answer += " Important concepts include: "
+                improved_answer += ", ".join(missing_keywords[:4]) + "."
+            
+            # Add some variety
+            attempt_count = len(previous_attempts) if previous_attempts else 1
+            if attempt_count > 1:
+                improved_answer += f" Additionally, this relates to fundamental principles of the domain."
+            
+            return improved_answer
+        
+        # Return initial (incomplete) answer
+        return base_answer
+    
+    def _generate_api_answer(
+        self, 
+        question: str, 
+        feedback: Optional[str] = None,
+        missing_keywords: Optional[List[str]] = None,
+        previous_attempts: Optional[List[Dict]] = None
+    ) -> str:
+        """
+        Generate answer using HuggingFace LLM API
+        
+        Constructs different prompts based on:
+        - Initial attempt: Clear, structured question
+        - Retry attempt: Includes feedback and missing concepts
+        """
+        if not self.client:
+            return self._generate_mock_answer(question, feedback, missing_keywords, previous_attempts)
+        
+        # Build prompt
+        if feedback and missing_keywords:
+            # Retry prompt with feedback
+            prompt = f"""You are a technical interview candidate who received feedback on your previous answer.
+
+Question: {question}
+
+Previous Feedback: {feedback}
+
+Missing Concepts: {', '.join(missing_keywords)}
+
+Please provide an IMPROVED answer that addresses the feedback and includes the missing concepts. Be clear, concise, and comprehensive."""
+        else:
+            # Initial prompt
+            prompt = f"""You are a technical interview candidate. Answer the following question clearly and comprehensively, covering all key concepts:
+
+Question: {question}
+
+Provide a well-structured answer:"""
+        
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": "You are a knowledgeable technical interview candidate."},
+                    {"role": "user", "content": prompt}
+                ],
+                temperature=0.7,
+                max_tokens=300
+            )
+            return response.choices[0].message.content.strip()
+        except Exception as e:
+            print(f"Error calling HuggingFace API: {e}")
+            return self._generate_mock_answer(question, feedback, missing_keywords, previous_attempts)
+    
+    def remember_attempt(
+        self, 
+        question: str, 
+        answer: str, 
+        score: float, 
+        feedback: str,
+        attempt: int
+    ):
+        """
+        Store attempt in memory for learning and analysis
+        
+        Memory allows agent to:
+        - Track improvement over time
+        - Analyze common mistakes
+        - Build knowledge base
+        
+        Args:
+            question: The question asked
+            answer: Answer provided
+            score: Score received
+            feedback: Feedback received
+            attempt: Attempt number
+        """
+        memory_entry = {
+            "question": question,
+            "answer": answer,
+            "score": score,
+            "feedback": feedback,
+            "attempt": attempt
+        }
+        
+        # Add to both global and question-specific memory
+        self.memory.append(memory_entry)
+        self.current_question_memory.append(memory_entry)
+    
+    def reset_question_memory(self):
+        """
+        Clear memory for current question
+        
+        Called when starting a new question/episode.
+        Keeps global memory but clears question-specific memory.
+        """
+        self.current_question_memory = []
+    
+    def get_improvement_stats(self) -> Dict[str, Any]:
+        """
+        Calculate improvement statistics from memory
+        
+        Returns:
+            Dictionary with:
+                - total_attempts: Total questions attempted
+                - average_score: Average score across all attempts
+                - improvement_rate: How much scores improved on retries
+                - total_retries: Number of retry attempts made
+        """
+        if not self.memory:
+            return {
+                "total_attempts": 0,
+                "average_score": 0.0,
+                "improvement_rate": 0.0,
+                "total_retries": 0
+            }
+        
+        scores = [m["score"] for m in self.memory]
+        retries = [m for m in self.memory if m["attempt"] > 1]
+        
+        # Calculate improvement rate
+        improvement_rate = 0.0
+        if len(self.current_question_memory) > 1:
+            first_score = self.current_question_memory[0]["score"]
+            last_score = self.current_question_memory[-1]["score"]
+            improvement_rate = last_score - first_score
+        
+        return {
+            "total_attempts": len(self.memory),
+            "average_score": sum(scores) / len(scores),
+            "improvement_rate": improvement_rate,
+            "total_retries": len(retries)
+        }
+    
+    def get_memory(self) -> List[Dict[str, Any]]:
+        """
+        Get complete memory
+        
+        Returns:
+            List of all stored attempts
+        """
+        return self.memory
+    
+    def get_current_question_memory(self) -> List[Dict[str, Any]]:
+        """
+        Get memory for current question only
+        
+        Returns:
+            List of attempts for current question
+        """
+        return self.current_question_memory

backend/app/dataset.json

@@ -0,0 +1,62 @@
+[
+  {
+    "question": "What is a binary search and what is its time complexity?",
+    "keywords": ["sorted array", "divide", "logarithmic", "O(log n)", "middle element", "halving"],
+    "difficulty": "easy"
+  },
+  {
+    "question": "Explain the difference between a process and a thread.",
+    "keywords": ["process", "thread", "memory space", "lightweight", "shared memory", "independent"],
+    "difficulty": "medium"
+  },
+  {
+    "question": "What is database normalization and why is it important?",
+    "keywords": ["redundancy", "normal forms", "dependency", "data integrity", "anomalies"],
+    "difficulty": "medium"
+  },
+  {
+    "question": "Explain the four pillars of Object-Oriented Programming.",
+    "keywords": ["encapsulation", "abstraction", "inheritance", "polymorphism"],
+    "difficulty": "easy"
+  },
+  {
+    "question": "What is a deadlock in operating systems and how can it be prevented?",
+    "keywords": ["mutual exclusion", "hold and wait", "circular wait", "prevention", "avoidance", "resources"],
+    "difficulty": "hard"
+  },
+  {
+    "question": "Explain how a hashmap works internally.",
+    "keywords": ["hash function", "buckets", "collision", "linked list", "O(1)", "array"],
+    "difficulty": "medium"
+  },
+  {
+    "question": "What is the difference between SQL and NoSQL databases?",
+    "keywords": ["structured", "schema", "scalability", "ACID", "flexible", "horizontal scaling"],
+    "difficulty": "easy"
+  },
+  {
+    "question": "Describe the SOLID principles in software design.",
+    "keywords": ["single responsibility", "open-closed", "liskov substitution", "interface segregation", "dependency inversion"],
+    "difficulty": "hard"
+  },
+  {
+    "question": "What is the difference between stack and heap memory?",
+    "keywords": ["static", "dynamic", "LIFO", "allocation", "scope", "lifetime"],
+    "difficulty": "medium"
+  },
+  {
+    "question": "Explain what a RESTful API is and its key constraints.",
+    "keywords": ["stateless", "client-server", "cacheable", "uniform interface", "HTTP methods", "resources"],
+    "difficulty": "medium"
+  },
+  {
+    "question": "What is Big O notation and why is it important?",
+    "keywords": ["time complexity", "space complexity", "worst case", "algorithm efficiency", "growth rate"],
+    "difficulty": "easy"
+  },
+  {
+    "question": "Explain the CAP theorem in distributed systems.",
+    "keywords": ["consistency", "availability", "partition tolerance", "distributed", "trade-off"],
+    "difficulty": "hard"
+  }
+]

backend/app/environment.py

@@ -0,0 +1,281 @@
+"""
+AI Interview Preparation Environment
+OpenAI Gym-style RL Environment for Interview Practice
+
+This module implements the core environment following the standard RL interface:
+- reset() -> returns initial state (question)
+- step(action) -> executes action and returns (reward, state, done, info)
+
+Features:
+- Random question selection from dataset
+- Episode history tracking
+- Configurable retry thresholds
+- Support for multi-turn episodes (extensible)
+"""
+
+import json
+import random
+from typing import Dict, Any, List
+from pathlib import Path
+
+
+class InterviewEnv:
+    """
+    Interview Preparation Environment
+    
+    This environment simulates a technical interview scenario where:
+    - State: Interview question with metadata (keywords, difficulty)
+    - Action: Candidate's answer (text string)
+    - Reward: Score-based reward computed by evaluator
+    
+    Design Decisions:
+    - Single question per episode (can be extended to multi-question)
+    - Stateful: maintains current question and episode history
+    - Delegated evaluation: uses injected evaluator for scoring
+    """
+    
+    def __init__(self, questions_path: str = None, evaluator=None):
+        """
+        Initialize the interview environment
+        
+        Args:
+            questions_path: Path to questions.json (defaults to ../data/questions.json)
+            evaluator: Evaluator instance for scoring answers (must implement evaluate())
+        """
+        # Set default path if not provided
+        if questions_path is None:
+            questions_path = Path(__file__).parent.parent / "data" / "questions.json"
+        
+        self.questions_path = questions_path
+        self.evaluator = evaluator
+        self.questions = self._load_questions()
+        
+        # State tracking
+        self.current_question = None
+        self.episode_history = []  # Stores all attempts in current episode
+        self.retry_count = 0
+        self.max_retries = 3  # Configurable retry limit
+        
+    def _load_questions(self) -> List[Dict[str, Any]]:
+        """
+        Load questions from JSON dataset
+        
+        Returns:
+            List of question dictionaries with structure:
+            {
+                "question": str,
+                "keywords": List[str],
+                "difficulty": str
+            }
+        """
+        try:
+            with open(self.questions_path, 'r') as f:
+                questions = json.load(f)
+            print(f"✅ Loaded {len(questions)} questions from {self.questions_path}")
+            return questions
+        except FileNotFoundError:
+            print(f"❌ Questions file not found: {self.questions_path}")
+            return []
+        except json.JSONDecodeError:
+            print(f"❌ Invalid JSON in questions file")
+            return []
+    
+    def reset(self) -> Dict[str, Any]:
+        """
+        Reset environment to initial state
+        
+        Selects a new random question and clears episode history.
+        This follows the Gym API convention.
+        
+        Returns:
+            state: Dictionary containing:
+                - question: The interview question text
+                - keywords: Expected keywords for evaluation
+                - difficulty: Question difficulty level
+                - attempt: Current attempt number (always 0 after reset)
+        """
+        # Select random question from dataset
+        if not self.questions:
+            raise ValueError("No questions loaded. Check questions.json")
+        
+        self.current_question = random.choice(self.questions)
+        self.episode_history = []
+        self.retry_count = 0
+        
+        # Return state representation
+        state = {
+            "question": self.current_question["question"],
+            "keywords": self.current_question["keywords"],
+            "difficulty": self.current_question["difficulty"],
+            "attempt": 0
+        }
+        
+        print(f"\n{'='*60}")
+        print(f"📝 NEW QUESTION [{state['difficulty'].upper()}]")
+        print(f"{'='*60}")
+        print(f"{state['question']}")
+        print(f"{'='*60}\n")
+        
+        return state
+    
+    def step(self, action: str) -> Dict[str, Any]:
+        """
+        Execute one environment step
+        
+        Takes the candidate's answer, evaluates it, and returns feedback.
+        This is the core of the RL loop.
+        
+        Args:
+            action: The candidate's answer (string)
+            
+        Returns:
+            Dictionary containing:
+                - reward: Integer reward signal (+10, +5, 0, -5)
+                - score: Float score (0.0 to 1.0)
+                - feedback: Structured feedback message
+                - matched_keywords: List of correctly mentioned keywords
+                - missing_keywords: List of missed keywords
+                - done: Boolean indicating if episode is complete
+                - attempt: Current attempt number
+                
+        Raises:
+            ValueError: If environment not initialized (call reset() first)
+        """
+        # Validation
+        if self.current_question is None:
+            raise ValueError("Environment not initialized. Call reset() first.")
+        
+        if self.evaluator is None:
+            raise ValueError("Evaluator not set. Pass evaluator to constructor.")
+        
+        # Evaluate the answer using injected evaluator
+        evaluation = self.evaluator.evaluate(
+            answer=action,
+            keywords=self.current_question["keywords"]
+        )
+        
+        # Extract evaluation results
+        score = evaluation["score"]
+        feedback = evaluation["feedback"]
+        matched_keywords = evaluation["matched_keywords"]
+        missing_keywords = evaluation["missing_keywords"]
+        
+        # Compute reward signal
+        reward = self.evaluator.compute_reward(score)
+        
+        # Increment retry counter
+        self.retry_count += 1
+        
+        # Store in episode history for memory/analysis
+        self.episode_history.append({
+            "attempt": self.retry_count,
+            "answer": action,
+            "score": score,
+            "reward": reward,
+            "matched_keywords": matched_keywords,
+            "missing_keywords": missing_keywords,
+            "feedback": feedback
+        })
+        
+        # Determine if episode is done
+        # Done if: high score OR max retries reached
+        done = (reward >= 0.9) or (self.retry_count >= self.max_retries)
+        
+        # Return full step information
+        return {
+            "reward": reward,
+            "score": score,
+            "feedback": feedback,
+            "matched_keywords": matched_keywords,
+            "missing_keywords": missing_keywords,
+            "done": done,
+            "attempt": self.retry_count,
+            "question": self.current_question["question"]
+        }
+    
+    def should_retry(self, reward: float) -> bool:
+        """
+        Determine if agent should attempt to improve answer
+        
+        Args:
+            reward: Current reward value (0.0 to 1.0)
+            
+        Returns:
+            True if agent should retry (low reward and retries available)
+        """
+        can_retry = self.retry_count < self.max_retries
+        needs_retry = reward < 0.7  # Threshold for improvement
+        
+        return can_retry and needs_retry
+    
+    def get_history(self) -> List[Dict[str, Any]]:
+        """
+        Get complete episode history
+        
+        Returns:
+            List of all attempts in current episode with full details
+        """
+        return self.episode_history
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get episode statistics
+        
+        Returns:
+            Dictionary with:
+                - total_attempts: Number of attempts made
+                - best_score: Highest score achieved
+                - improvement: Score improvement from first to last
+                - final_reward: Final reward value
+        """
+        if not self.episode_history:
+            return {
+                "total_attempts": 0,
+                "best_score": 0.0,
+                "improvement": 0.0,
+                "final_reward": 0
+            }
+        
+        scores = [h["score"] for h in self.episode_history]
+        rewards = [h["reward"] for h in self.episode_history]
+        
+        return {
+            "total_attempts": len(self.episode_history),
+            "best_score": max(scores),
+            "improvement": scores[-1] - scores[0] if len(scores) > 1 else 0.0,
+            "final_reward": rewards[-1]
+        }
+    
+    def set_max_retries(self, max_retries: int):
+        """
+        Configure maximum retry attempts
+        
+        Args:
+            max_retries: Maximum number of attempts allowed
+        """
+        self.max_retries = max_retries
+    
+    def state(self) -> Dict[str, Any]:
+        """
+        Get current environment state
+        
+        OpenEnv-compliant state getter.
+        Returns current question and attempt information.
+        
+        Returns:
+            Dictionary containing:
+                - question: Current question text
+                - difficulty: Question difficulty level
+                - attempt: Current attempt number
+                
+        Raises:
+            ValueError: If environment not initialized (call reset() first)
+        """
+        if self.current_question is None:
+            raise ValueError("Environment not initialized. Call reset() first.")
+        
+        return {
+            "question": self.current_question["question"],
+            "difficulty": self.current_question["difficulty"],
+            "attempt": self.retry_count
+        }

backend/app/evaluator.py

@@ -0,0 +1,310 @@
+"""
+Advanced Evaluator with Hybrid Scoring System
+Evaluates interview answers using multiple metrics
+
+Features:
+- Keyword-based scoring (primary)
+- AI-based scoring (placeholder/mock - extensible)
+- Structured feedback generation
+- Reward computation for RL
+- Text normalization for robust matching
+
+Design Philosophy:
+- Modular: Easy to swap keyword logic or add LLM judge
+- Extensible: Hybrid scoring allows future AI integration
+- Explainable: Returns detailed feedback and matched/missing keywords
+"""
+
+import re
+from typing import Dict, List, Any, Tuple
+
+
+class Evaluator:
+    """
+    Hybrid Answer Evaluator
+    
+    Evaluates answers using:
+    1. Keyword matching (primary metric)
+    2. AI scoring (placeholder for LLM-as-judge)
+    
+    Final score = 0.7 * keyword_score + 0.3 * ai_score
+    
+    This allows:
+    - Fast, deterministic evaluation (keywords)
+    - Future semantic understanding (AI judge)
+    - Explainable results (specific missing concepts)
+    """
+    
+    def __init__(self, keyword_weight: float = 0.8, ai_weight: float = 0.2):
+        """
+        Initialize evaluator with scoring weights
+        
+        Args:
+            keyword_weight: Weight for keyword-based score (default 0.8)
+            ai_weight: Weight for length-based score (default 0.2)
+            
+        Weights should sum to 1.0 for normalized scoring
+        """
+        self.keyword_weight = keyword_weight
+        self.ai_weight = ai_weight
+        
+        # Validate weights
+        if not abs((keyword_weight + ai_weight) - 1.0) < 0.01:
+            print(f"⚠️  Warning: Weights don't sum to 1.0 ({keyword_weight + ai_weight})")
+    
+    def normalize_text(self, text: str) -> str:
+        """
+        Normalize text for robust keyword matching
+        
+        Steps:
+        1. Convert to lowercase
+        2. Remove special characters (keep alphanumeric, spaces, hyphens, parens)
+        3. Collapse multiple spaces
+        
+        Args:
+            text: Raw text string
+            
+        Returns:
+            Normalized text string
+            
+        Examples:
+            "O(log n)" -> "o(log n)"
+            "Process!!!" -> "process"
+            "REST  API" -> "rest api"
+        """
+        text = text.lower()
+        
+        # Keep alphanumeric, spaces, hyphens, and parentheses
+        # This preserves "O(log n)", "client-server", etc.
+        text = re.sub(r'[^a-z0-9\s\-\(\)]', ' ', text)
+        
+        # Collapse multiple spaces
+        text = ' '.join(text.split())
+        
+        return text
+    
+    def evaluate_keywords(self, answer: str, keywords: List[str]) -> Tuple[float, List[str], List[str]]:
+        """
+        Evaluate answer based on keyword coverage
+        
+        This is the primary evaluation metric.
+        
+        Args:
+            answer: Candidate's answer text
+            keywords: List of expected keywords/phrases
+            
+        Returns:
+            Tuple of (score, matched_keywords, missing_keywords)
+            - score: Proportion of keywords found (0.0 to 1.0)
+            - matched_keywords: Keywords found in answer
+            - missing_keywords: Keywords not found in answer
+            
+        Algorithm:
+        1. Normalize both answer and keywords
+        2. Check if each keyword appears in answer (substring match)
+        3. Calculate score as ratio: matched / total
+        """
+        if not answer or not answer.strip():
+            return 0.0, [], keywords
+        
+        normalized_answer = self.normalize_text(answer)
+        matched_keywords = []
+        missing_keywords = []
+        
+        # Check each keyword
+        for keyword in keywords:
+            normalized_keyword = self.normalize_text(keyword)
+            
+            # Use substring matching for flexibility
+            # "O(log n)" matches "time complexity is O(log n)"
+            if normalized_keyword in normalized_answer:
+                matched_keywords.append(keyword)
+            else:
+                missing_keywords.append(keyword)
+        
+        # Calculate proportional score
+        if len(keywords) == 0:
+            keyword_score = 0.5  # Neutral score if no keywords defined
+        else:
+            keyword_score = len(matched_keywords) / len(keywords)
+        
+        return keyword_score, matched_keywords, missing_keywords
+    
+    def evaluate_ai(self, answer: str, question: str = None) -> float:
+        """
+        Length-based evaluation (deterministic)
+        
+        DETERMINISTIC implementation for OpenEnv compliance.
+        Scores based on answer length relative to ideal length.
+        
+        Current implementation:
+        - Deterministic scoring based on answer length
+        - No randomness - same input always gives same output
+        - Considers completeness via length heuristic
+        
+        Args:
+            answer: Candidate's answer
+            question: Original question (for context)
+            
+        Returns:
+            Length score between 0.0 and 1.0
+        """
+        # DETERMINISTIC IMPLEMENTATION for OpenEnv compliance
+        
+        # Ideal answer length: 100-300 characters
+        # Score based on how close to ideal range
+        if not answer or len(answer.strip()) < 10:
+            return 0.2
+        
+        answer_length = len(answer.strip())
+        
+        # Optimal range: 100-300 characters
+        if 100 <= answer_length <= 300:
+            return 1.0
+        elif answer_length < 100:
+            # Scale from 0.5 to 1.0 as length approaches 100
+            return 0.5 + 0.5 * (answer_length / 100.0)
+        else:
+            # Penalize excessively long answers (diminishing returns)
+            excess = answer_length - 300
+            penalty = min(excess / 500.0, 0.3)  # Max 0.3 penalty
+            return max(0.7, 1.0 - penalty)
+        
+
+    
+    def evaluate(self, answer: str, keywords: List[str], question: str = None) -> Dict[str, Any]:
+        """
+        Complete hybrid evaluation
+        
+        Combines keyword-based and AI-based scoring with configurable weights.
+        
+        Args:
+            answer: Candidate's answer
+            keywords: Expected keywords for this question
+            question: Original question (optional, for AI judge)
+            
+        Returns:
+            Dictionary containing:
+                - score: Final hybrid score (0.0 to 1.0)
+                - keyword_score: Keyword-based score
+                - ai_score: AI-based score
+                - matched_keywords: Keywords found
+                - missing_keywords: Keywords not found
+                - feedback: Human-readable feedback string
+        """
+        # Evaluate using both methods
+        keyword_score, matched, missing = self.evaluate_keywords(answer, keywords)
+        ai_score = self.evaluate_ai(answer, question)
+        
+        # Compute weighted hybrid score
+        final_score = (self.keyword_weight * keyword_score) + (self.ai_weight * ai_score)
+        
+        # Generate structured feedback
+        feedback = self._generate_feedback(
+            score=final_score,
+            keyword_score=keyword_score,
+            matched=matched,
+            missing=missing
+        )
+        
+        return {
+            "score": final_score,
+            "keyword_score": keyword_score,
+            "ai_score": ai_score,
+            "matched_keywords": matched,
+            "missing_keywords": missing,
+            "feedback": feedback
+        }
+    
+    def _generate_feedback(
+        self, 
+        score: float, 
+        keyword_score: float,
+        matched: List[str], 
+        missing: List[str]
+    ) -> str:
+        """
+        Generate structured, actionable feedback
+        
+        Feedback is designed to be:
+        - Clear and specific
+        - Actionable (tells what to add)
+        - Encouraging (positive framing)
+        - Machine-parseable (for agent improvement)
+        
+        Args:
+            score: Final score
+            keyword_score: Keyword coverage score
+            matched: Matched keywords
+            missing: Missing keywords
+            
+        Returns:
+            Formatted feedback string
+        """
+        total_keywords = len(matched) + len(missing)
+        
+        # Score-based feedback tier
+        if score >= 0.8:
+            base = f"✅ Excellent answer! "
+            base += f"Covered {len(matched)}/{total_keywords} key concepts."
+            if matched:
+                base += f"\n   ✓ Mentioned: {', '.join(matched)}"
+            return base
+        
+        elif score >= 0.5:
+            base = f"👍 Good answer. "
+            base += f"Covered {len(matched)}/{total_keywords} concepts."
+            if matched:
+                base += f"\n   ✓ Covered: {', '.join(matched)}"
+            if missing:
+                # Show up to 3 missing keywords for actionable feedback
+                base += f"\n   ⚠ Consider adding: {', '.join(missing[:3])}"
+            return base
+        
+        elif score >= 0.3:
+            base = f"⚠️  Partial answer. "
+            base += f"Only {len(matched)}/{total_keywords} concepts covered."
+            if matched:
+                base += f"\n   ✓ Included: {', '.join(matched)}"
+            if missing:
+                base += f"\n   ✗ Missing: {', '.join(missing)}"
+            return base
+        
+        else:
+            base = f"❌ Weak answer. "
+            base += f"Missing {len(missing)}/{total_keywords} critical concepts."
+            if missing:
+                base += f"\n   ✗ Must include: {', '.join(missing)}"
+            base += "\n   💡 Tip: Cover fundamental concepts first"
+            return base
+    
+    def compute_reward(self, score: float) -> float:
+        """
+        Convert score to RL reward signal
+        
+        OpenEnv-compliant reward function:
+        - Reward is IDENTICAL to score (0.0 to 1.0 range)
+        - Deterministic: same score always gives same reward
+        - Continuous: allows fine-grained learning signals
+        
+        Args:
+            score: Evaluation score (0.0 to 1.0)
+            
+        Returns:
+            Float reward value (0.0 to 1.0)
+        """
+        # OpenEnv compliance: reward = score (0.0 to 1.0)
+        return float(score)
+    
+    def set_weights(self, keyword_weight: float, ai_weight: float):
+        """
+        Update scoring weights
+        
+        Allows runtime adjustment of hybrid scoring balance.
+        
+        Args:
+            keyword_weight: New keyword weight
+            ai_weight: New AI weight
+        """
+        self.keyword_weight = keyword_weight
+        self.ai_weight = ai_weight

backend/main.py

@@ -0,0 +1,332 @@
+"""
+FastAPI Backend for AI Interview Preparation RL Environment
+OpenEnv-compliant API implementation
+"""
+
+import os
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from typing import Optional
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+print("🚀 Server starting...")
+
+# Import from app package
+from app.environment import InterviewEnv
+from app.evaluator import Evaluator
+from app.agent import InterviewAgent
+
+
+# Initialize FastAPI app
+app = FastAPI(title="AI Interview Prep RL Environment")
+
+# CORS middleware for frontend
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize components
+evaluator = Evaluator()
+
+# Resolve dataset path — works in both local (backend/) and Docker (/app/) contexts
+questions_path = Path(__file__).resolve().parent / "app" / "dataset.json"
+print(f"📂 Dataset path: {questions_path}")
+print(f"📂 Dataset exists: {questions_path.exists()}")
+
+env = InterviewEnv(questions_path=str(questions_path), evaluator=evaluator)
+
+# Graceful agent init — don't crash server if API key is missing
+try:
+    agent = InterviewAgent(mode="api")  # Will use HF_TOKEN from .env
+    print(f"🤖 Agent initialized in mode: {agent.mode}")
+except Exception as e:
+    print(f"⚠️  Agent init failed ({e}), using mock mode")
+    agent = InterviewAgent(mode="mock")
+
+print("✅ All components initialized successfully")
+
+# Global state
+current_state = None
+current_config = {
+    "api_key": None,
+    "model": "Qwen/Qwen3-Coder-Next:novita"
+}
+
+
+# Request/Response models
+class StepRequest(BaseModel):
+    action: str
+
+
+class AnswerRequest(BaseModel):
+    answer: str
+
+
+class AutoRunRequest(BaseModel):
+    use_retry: bool = True
+
+
+class ConfigRequest(BaseModel):
+    api_key: str
+    model: str = "Qwen/Qwen3-Coder-Next:novita"
+
+
+@app.get("/")
+def read_root():
+    """Root endpoint"""
+    return {
+        "message": "AI Interview Preparation RL Environment (OpenEnv Compliant)",
+        "status": "running",
+        "endpoints": ["/reset", "/step", "/state", "/question", "/answer", "/auto-run", "/stats", "/config"]
+    }
+
+
+# OpenEnv-compliant endpoints
+
+@app.post("/reset")
+def reset():
+    """OpenEnv: Reset environment and get new question"""
+    global current_state
+    
+    try:
+        current_state = env.reset()
+        # Return only the required fields for OpenEnv compliance
+        return {
+            "question": current_state["question"],
+            "difficulty": current_state["difficulty"],
+            "attempt": current_state["attempt"]
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/step")
+def step(request: StepRequest):
+    """OpenEnv: Submit action and get reward"""
+    global current_state
+    
+    if current_state is None:
+        raise HTTPException(status_code=400, detail="Environment not initialized. Call /reset first")
+    
+    try:
+        result = env.step(request.action)
+        
+        # Get current state
+        state_data = env.state()
+        
+        # Return OpenEnv-compliant response
+        return {
+            "reward": result["reward"],
+            "done": result["done"],
+            "state": state_data
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/state")
+def get_state():
+    """OpenEnv: Get current environment state"""
+    if current_state is None:
+        raise HTTPException(status_code=400, detail="Environment not initialized. Call /reset first")
+    
+    try:
+        state_data = env.state()
+        return state_data
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# Legacy endpoints (for backward compatibility with existing frontend)
+
+@app.get("/question")
+def get_question():
+    """Get a new interview question (calls env.reset())"""
+    global current_state
+    
+    try:
+        current_state = env.reset()
+        return {
+            "status": "success",
+            "state": current_state
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/answer")
+def submit_answer(request: AnswerRequest):
+    """Submit an answer and get evaluation (calls env.step())"""
+    global current_state
+    
+    if current_state is None:
+        raise HTTPException(status_code=400, detail="No active question. Call /question first")
+    
+    try:
+        result = env.step(request.answer)
+        return {
+            "status": "success",
+            "result": result
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/auto-run")
+def auto_run(request: AutoRunRequest):
+    """Automatic RL episode - agent generates and improves answer"""
+    global current_state
+    
+    try:
+        # Reset environment
+        current_state = env.reset()
+        question = current_state["question"]
+        
+        # Agent generates initial answer
+        answer = agent.generate_answer(question)
+        
+        # Evaluate
+        result = env.step(answer)
+        
+        episode_data = {
+            "question": question,
+            "difficulty": current_state["difficulty"],
+            "attempt_1": {
+                "answer": answer,
+                "score": result["score"],
+                "reward": result["reward"],
+                "feedback": result["feedback"]
+            }
+        }
+        
+        # Retry logic if enabled and reward is low
+        if request.use_retry and env.should_retry(result["reward"]):
+            # Reset for retry
+            current_state = {
+                "question": question,
+                "keywords": current_state["keywords"],
+                "difficulty": current_state["difficulty"]
+            }
+            env.current_question = {
+                "question": question,
+                "keywords": current_state["keywords"],
+                "difficulty": current_state["difficulty"]
+            }
+            
+            # Generate improved answer with feedback
+            improved_answer = agent.generate_answer(
+                question,
+                feedback=result["feedback"],
+                missing_keywords=result.get("missing_keywords", [])
+            )
+            
+            # Evaluate again
+            retry_result = env.step(improved_answer)
+            
+            episode_data["attempt_2"] = {
+                "answer": improved_answer,
+                "score": retry_result["score"],
+                "reward": retry_result["reward"],
+                "feedback": retry_result["feedback"]
+            }
+            
+            episode_data["improvement"] = retry_result["score"] - result["score"]
+        
+        return {
+            "status": "success",
+            "episode": episode_data
+        }
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/config")
+def update_config(request: ConfigRequest):
+    """Update API configuration (API key and model)"""
+    global agent, current_config
+    
+    try:
+        # Update configuration
+        current_config["api_key"] = request.api_key
+        current_config["model"] = request.model
+        
+        # Reinitialize agent with new configuration
+        agent = InterviewAgent(mode="api", api_key=request.api_key, model=request.model)
+        
+        # Check if agent has proper client initialization
+        has_client = hasattr(agent, 'client') and agent.client is not None
+        
+        return {
+            "status": "success",
+            "message": "Configuration updated successfully",
+            "config": {
+                "model": request.model,
+                "api_key_set": bool(request.api_key),
+                "client_initialized": has_client
+            }
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Configuration error: {str(e)}")
+
+
+@app.get("/config")
+def get_config():
+    """Get current API configuration"""
+    has_client = hasattr(agent, 'client') and agent.client is not None
+    
+    return {
+        "status": "success",
+        "config": {
+            "model": current_config["model"],
+            "api_key_set": bool(current_config["api_key"]),
+            "client_initialized": has_client
+        }
+    }
+
+
+@app.get("/stats")
+def get_stats():
+    """Get episode statistics"""
+    try:
+        history = env.get_history()
+        if not history:
+            return {
+                "status": "success",
+                "stats": {
+                    "total_attempts": 0,
+                    "average_score": 0,
+                    "average_reward": 0
+                }
+            }
+        
+        avg_score = sum(h["score"] for h in history) / len(history)
+        avg_reward = sum(h["reward"] for h in history) / len(history)
+        
+        return {
+            "status": "success",
+            "stats": {
+                "total_attempts": len(history),
+                "average_score": round(avg_score, 3),
+                "average_reward": round(avg_reward, 2),
+                "history": history
+            }
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.getenv("PORT", "8000"))
+    print(f"🌐 Starting server on port {port}")
+    uvicorn.run(app, host="0.0.0.0", port=port)

backend/main_old.py

@@ -0,0 +1,291 @@
+"""
+FastAPI Backend for AI Interview Preparation RL Environment
+"""
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from typing import Optional
+import sys
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Add parent directory to path
+sys.path.append(str(Path(__file__).parent))
+
+from env.interview_env import InterviewEnv
+from evaluator.evaluator import Evaluator
+from agent.llm_agent import LLMAgent
+
+
+# Initialize FastAPI app
+app = FastAPI(title="AI Interview Prep RL Environment")
+
+# CORS middleware for frontend
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, specify exact origins
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize components
+evaluator = Evaluator()
+env = InterviewEnv(evaluator=evaluator)
+agent = LLMAgent()
+
+# Global state (in production, use session management)
+current_state = None
+current_config = {
+    "api_key": None,
+    "model": "Qwen/Qwen3-Coder-Next:novita"
+}
+
+
+# Request/Response models
+class AnswerRequest(BaseModel):
+    answer: str
+
+
+class AutoRunRequest(BaseModel):
+    use_retry: bool = True
+
+
+class ConfigRequest(BaseModel):
+    api_key: str
+    model: str = "Qwen/Qwen3-Coder-Next:novita"
+
+
+@app.get("/")
+def read_root():
+    """Root endpoint"""
+    return {
+        "message": "AI Interview Preparation RL Environment",
+        "status": "running",
+        "endpoints": ["/question", "/answer", "/auto-run", "/stats", "/config"]
+    }
+
+
+@app.get("/question")
+def get_question():
+    """
+    Get a new interview question (calls env.reset())
+    
+    Returns:
+        {
+            "question": str,
+            "keywords": list,
+            "difficulty": str
+        }
+    """
+    global current_state
+    
+    try:
+        current_state = env.reset()
+        return {
+            "status": "success",
+            "state": current_state
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/answer")
+def submit_answer(request: AnswerRequest):
+    """
+    Submit an answer and get evaluation (calls env.step())
+    
+    Args:
+        answer: The candidate's answer
+        
+    Returns:
+        {
+            "reward": int,
+            "score": float,
+            "feedback": str,
+            "missing_keywords": list,
+            "done": bool
+        }
+    """
+    global current_state
+    
+    if current_state is None:
+        raise HTTPException(
+            status_code=400, 
+            detail="No active question. Call /question first"
+        )
+    
+    try:
+        result = env.step(request.answer)
+        return {
+            "status": "success",
+            "result": result
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/auto-run")
+def auto_run(request: AutoRunRequest):
+    """
+    Automatic RL loop: Get question → Agent generates answer → Evaluate → Optional retry
+    
+    Args:
+        use_retry: Whether to retry on low scores
+        
+    Returns:
+        Complete episode results with optional retry
+    """
+    global current_state
+    
+    try:
+        # Reset environment and get question
+        current_state = env.reset()
+        question = current_state["question"]
+        
+        # Agent generates initial answer
+        answer = agent.generate_answer(question)
+        
+        # Evaluate
+        result = env.step(answer)
+        
+        episode_data = {
+            "question": question,
+            "difficulty": current_state["difficulty"],
+            "attempt_1": {
+                "answer": answer,
+                "score": result["score"],
+                "reward": result["reward"],
+                "feedback": result["feedback"]
+            }
+        }
+        
+        # Retry logic if enabled and reward is low
+        if request.use_retry and env.should_retry(result["reward"]):
+            # Reset for retry
+            current_state = {
+                "question": question,
+                "keywords": current_state["keywords"],
+                "difficulty": current_state["difficulty"]
+            }
+            env.current_question = {
+                "question": question,
+                "keywords": current_state["keywords"],
+                "difficulty": current_state["difficulty"]
+            }
+            
+            # Generate improved answer with feedback
+            improved_answer = agent.generate_answer(question, result["feedback"])
+            
+            # Evaluate again
+            retry_result = env.step(improved_answer)
+            
+            episode_data["attempt_2"] = {
+                "answer": improved_answer,
+                "score": retry_result["score"],
+                "reward": retry_result["reward"],
+                "feedback": retry_result["feedback"]
+            }
+            
+            episode_data["improvement"] = retry_result["score"] - result["score"]
+        
+        return {
+            "status": "success",
+            "episode": episode_data
+        }
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/config")
+def update_config(request: ConfigRequest):
+    """
+    Update API configuration (API key and model)
+    
+    Args:
+        api_key: Hugging Face API token
+        model: Model name/endpoint to use
+        
+    Returns:
+        Configuration status
+    """
+    global agent, current_config
+    
+    try:
+        # Update configuration
+        current_config["api_key"] = request.api_key
+        current_config["model"] = request.model
+        
+        # Reinitialize agent with new configuration
+        agent = LLMAgent(api_key=request.api_key, model=request.model)
+        
+        return {
+            "status": "success",
+            "message": "Configuration updated successfully",
+            "config": {
+                "model": request.model,
+                "api_key_set": bool(request.api_key),
+                "client_initialized": bool(agent.client)
+            }
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Configuration error: {str(e)}")
+
+
+@app.get("/config")
+def get_config():
+    """
+    Get current API configuration
+    
+    Returns:
+        Current configuration (without exposing full API key)
+    """
+    return {
+        "status": "success",
+        "config": {
+            "model": current_config["model"],
+            "api_key_set": bool(current_config["api_key"]),
+            "client_initialized": bool(agent.client)
+        }
+    }
+
+
+@app.get("/stats")
+def get_stats():
+    """Get episode statistics"""
+    try:
+        history = env.get_history()
+        if not history:
+            return {
+                "status": "success",
+                "stats": {
+                    "total_attempts": 0,
+                    "average_score": 0,
+                    "average_reward": 0
+                }
+            }
+        
+        avg_score = sum(h["score"] for h in history) / len(history)
+        avg_reward = sum(h["reward"] for h in history) / len(history)
+        
+        return {
+            "status": "success",
+            "stats": {
+                "total_attempts": len(history),
+                "average_score": round(avg_score, 3),
+                "average_reward": round(avg_reward, 2),
+                "history": history
+            }
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

backend/requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.104.1
+uvicorn==0.24.0
+pydantic==2.5.0
+openai==1.57.4
+python-multipart==0.0.6
+python-dotenv==1.0.0

backend/test_env.py

@@ -0,0 +1,96 @@
+"""
+Test script to verify the RL environment works correctly
+Run this before starting the full application
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.append(str(Path(__file__).parent))
+
+from env.interview_env import InterviewEnv
+from evaluator.evaluator import Evaluator
+from agent.llm_agent import LLMAgent
+
+
+def test_environment():
+    """Test the RL environment"""
+    print("=" * 60)
+    print("🧪 TESTING RL ENVIRONMENT")
+    print("=" * 60)
+    
+    # Initialize components
+    evaluator = Evaluator()
+    env = InterviewEnv(evaluator=evaluator)
+    agent = LLMAgent()
+    
+    print("\n✅ Components initialized successfully\n")
+    
+    # Test 1: Reset environment
+    print("📝 Test 1: Environment Reset")
+    print("-" * 60)
+    state = env.reset()
+    print(f"Question: {state['question']}")
+    print(f"Difficulty: {state['difficulty']}")
+    print(f"Keywords: {', '.join(state['keywords'])}")
+    print("✅ Reset successful\n")
+    
+    # Test 2: Evaluate a good answer
+    print("📝 Test 2: Evaluate Good Answer")
+    print("-" * 60)
+    good_answer = " ".join(state['keywords'][:3])  # Include some keywords
+    result = env.step(good_answer)
+    print(f"Answer: {good_answer}")
+    print(f"Score: {result['score']:.2%}")
+    print(f"Reward: {result['reward']}")
+    print(f"Feedback: {result['feedback']}")
+    print("✅ Evaluation successful\n")
+    
+    # Test 3: Generate AI answer
+    print("📝 Test 3: AI Agent Answer Generation")
+    print("-" * 60)
+    env.reset()  # Get new question
+    question = env.current_question['question']
+    ai_answer = agent.generate_answer(question)
+    print(f"Question: {question}")
+    print(f"AI Answer: {ai_answer}")
+    result = env.step(ai_answer)
+    print(f"Score: {result['score']:.2%}")
+    print(f"Reward: {result['reward']}")
+    print(f"Feedback: {result['feedback']}")
+    print("✅ AI generation successful\n")
+    
+    # Test 4: Retry mechanism
+    print("📝 Test 4: Retry Mechanism")
+    print("-" * 60)
+    if env.should_retry(result['reward']):
+        print("⚠️  Low reward detected - initiating retry")
+        improved_answer = agent.generate_answer(question, result['feedback'])
+        
+        # Reset to same question for retry
+        env.current_question = {
+            "question": question,
+            "keywords": state['keywords'],
+            "difficulty": state['difficulty']
+        }
+        
+        retry_result = env.step(improved_answer)
+        print(f"Improved Answer: {improved_answer}")
+        print(f"New Score: {retry_result['score']:.2%}")
+        print(f"New Reward: {retry_result['reward']}")
+        improvement = retry_result['score'] - result['score']
+        print(f"Improvement: {improvement:+.2%}")
+        print("✅ Retry successful\n")
+    else:
+        print("✅ Score was good - no retry needed\n")
+    
+    print("=" * 60)
+    print("✅ ALL TESTS PASSED!")
+    print("=" * 60)
+    print("\nYou can now start the FastAPI server with:")
+    print("  python main.py")
+
+
+if __name__ == "__main__":
+    test_environment()

inference.py

@@ -0,0 +1,93 @@
+"""
+OpenEnv-compliant inference script
+Runs complete episode over all tasks with exact logging format
+"""
+
+import os
+import sys
+import json
+from pathlib import Path
+
+# Add backend to path
+sys.path.insert(0, str(Path(__file__).parent / "backend"))
+
+from app.environment import InterviewEnv
+from app.evaluator import Evaluator
+from app.agent import InterviewAgent
+
+
+def run_inference():
+    """
+    Run inference over all tasks with OpenEnv-compliant logging
+    
+    Environment variables:
+    - API_BASE_URL: LLM API endpoint
+    - MODEL_NAME: Model identifier
+    - HF_TOKEN: API authentication token
+    """
+    
+    # Get environment variables
+    api_base_url = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+    model_name = os.getenv("MODEL_NAME", "Qwen/Qwen3-Coder-Next:novita")
+    hf_token = os.getenv("HF_TOKEN")
+    
+    # Initialize components
+    evaluator = Evaluator()
+    questions_path = Path(__file__).parent / "backend" / "app" / "dataset.json"
+    env = InterviewEnv(questions_path=str(questions_path), evaluator=evaluator)
+    
+    # Initialize agent (will use mock mode if no token)
+    if hf_token:
+        agent = InterviewAgent(mode="api", api_key=hf_token, model=model_name)
+    else:
+        print("⚠️  No HF_TOKEN found, using mock mode")
+        agent = InterviewAgent(mode="mock")
+    
+    # Load all tasks
+    with open(questions_path, 'r') as f:
+        tasks = json.load(f)
+    
+    print(f"Running inference on {len(tasks)} tasks")
+    print(f"API Base URL: {api_base_url}")
+    print(f"Model: {model_name}")
+    print("-" * 80)
+    
+    # Run inference on each task
+    for task_idx, task in enumerate(tasks):
+        task_id = f"task_{task_idx}"
+        
+        # Print START marker
+        print(f"[START]")
+        print(f"task_id={task_id}")
+        
+        # Reset environment to this specific task
+        env.current_question = task
+        env.episode_history = []
+        env.retry_count = 0
+        
+        question = task["question"]
+        
+        # Generate answer
+        answer = agent.generate_answer(question)
+        
+        # Print STEP marker with action
+        print(f"[STEP]")
+        print(f"action={answer}")
+        
+        # Evaluate
+        result = env.step(answer)
+        reward = result["reward"]
+        
+        # Print reward
+        print(f"reward={reward}")
+        
+        # Print END marker
+        print(f"[END]")
+        print()
+    
+    print("-" * 80)
+    print(f"✅ Inference complete: {len(tasks)} tasks processed")
+
+
+if __name__ == "__main__":
+    run_inference()

openenv.yaml

@@ -0,0 +1,111 @@
+name: ai-interview-prep-rl-env
+description: Reinforcement Learning environment for AI-powered technical interview preparation with keyword-based evaluation and retry mechanism
+
+endpoints:
+  reset:
+    method: POST
+    path: /reset
+    description: Reset environment and get new interview question
+    response_schema:
+      type: object
+      properties:
+        question:
+          type: string
+          description: Interview question text
+        difficulty:
+          type: string
+          description: Question difficulty level (easy, medium, hard)
+        attempt:
+          type: integer
+          description: Current attempt number (0 after reset)
+      required:
+        - question
+        - difficulty
+        - attempt
+  
+  step:
+    method: POST
+    path: /step
+    description: Submit answer and get evaluation with reward
+    request_schema:
+      type: object
+      properties:
+        action:
+          type: string
+          description: Candidate's answer to the question
+      required:
+        - action
+    response_schema:
+      type: object
+      properties:
+        reward:
+          type: number
+          description: Reward signal between 0.0 and 1.0
+          minimum: 0.0
+          maximum: 1.0
+        done:
+          type: boolean
+          description: Whether episode is complete
+        state:
+          type: object
+          properties:
+            question:
+              type: string
+            difficulty:
+              type: string
+            attempt:
+              type: integer
+          required:
+            - question
+            - difficulty
+            - attempt
+      required:
+        - reward
+        - done
+        - state
+  
+  state:
+    method: GET
+    path: /state
+    description: Get current environment state
+    response_schema:
+      type: object
+      properties:
+        question:
+          type: string
+          description: Current interview question
+        difficulty:
+          type: string
+          description: Question difficulty level
+        attempt:
+          type: integer
+          description: Current attempt number
+      required:
+        - question
+        - difficulty
+        - attempt
+
+tasks:
+  count: 12
+  source: backend/app/dataset.json
+  description: Technical interview questions covering algorithms, systems, databases, and software design
+
+grading:
+  type: hybrid
+  deterministic: true
+  components:
+    - keyword_matching: 0.8
+    - length_scoring: 0.2
+  output_range:
+    min: 0.0
+    max: 1.0
+
+environment:
+  type: single_question_episode
+  max_retries: 3
+  state_representation:
+    - question: string
+    - difficulty: string
+    - attempt: integer
+  action_space: text
+  reward_range: [0.0, 1.0]