diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000000000000000000000000000000000..c4ef162b6a91aa4f0d17b9ca22a6f9c6a0e9880c --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +backend/ml/artifacts/kt_model.onnx filter=lfs diff=lfs merge=lfs -text diff --git a/.gitignore b/.gitignore index 2b29ee59fa701cd8fb8dd2ae711ef4e4a62dcd2c..fdfa2d45a6f8fcb5b170e9cbfdf8e2b507bbe60b 100644 --- a/.gitignore +++ b/.gitignore @@ -59,3 +59,9 @@ yarn-error.log* # Misc output.txt + +# Training artefacts (downloaded data, logs, sweep results) +training/data_cache/ +training/logs/ +training/results/*_sweep_*.json +backend/tests/__pycache__/ diff --git a/.python-version b/.python-version deleted file mode 100644 index 7b59a5caab64ba0eb4eacb12af7e3a55206788be..0000000000000000000000000000000000000000 --- a/.python-version +++ /dev/null @@ -1 +0,0 @@ -3.10.2 diff --git a/Dockerfile b/Dockerfile index f2cf3bb5c38b1fb3e216d0693d4ee0625d922a4e..e58c817647311dfa7949316c4bb0831fda3e5e51 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,32 +1,26 @@ -FROM python:3.10-slim +# Hugging Face Space image (sdk: docker, app_port: 7860). Serves the Flask API in backend/. +FROM python:3.11-slim -# Set environment variables -ENV PYTHONDONTWRITEBYTECODE 1 -ENV PYTHONUNBUFFERED 1 -ENV PORT 7860 +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + PIP_NO_CACHE_DIR=1 \ + PORT=7860 +# HF Spaces run containers as uid 1000 +RUN useradd -m -u 1000 user WORKDIR /app -# Install system dependencies -RUN apt-get update && apt-get install -y --no-install-recommends \ - build-essential \ - && rm -rf /var/lib/apt/lists/* +COPY backend/requirements.txt /app/backend/requirements.txt +RUN pip install -r /app/backend/requirements.txt -# Copy requirements from backend and install -COPY backend/requirements.txt . -RUN pip install --no-cache-dir -r requirements.txt +COPY --chown=user backend /app/backend +RUN mkdir -p /app/data && chown -R user /app/data -# Copy the entire project -COPY . . - -# Create data directory -RUN mkdir -p /app/data - -# Final working directory for the app +USER user WORKDIR /app/backend - -# Expose port EXPOSE 7860 -# Run the backend app -CMD ["gunicorn", "--bind", "0.0.0.0:7860", "--timeout", "120", "--workers", "1", "app:app"] +HEALTHCHECK --interval=30s --timeout=5s --start-period=30s CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:7860/api/health')" + +# One process (the DB seeding and the in-process metrics assume it); threads for concurrency. +CMD ["gunicorn", "--bind", "0.0.0.0:7860", "--workers", "1", "--threads", "8", "--worker-class", "gthread", "--timeout", "180", "app:app"] diff --git a/README.md b/README.md index 25371109363c29302fc0554f7677e176993805a5..f5a4bc89d0897929eef59c0293cefa1f136e2106 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,115 @@ --- title: Adaptive Elearning Backend emoji: 🧠 -colorFrom: indigo -colorTo: blue +colorFrom: yellow +colorTo: gray sdk: docker app_port: 7860 pinned: false --- -# Multi-Agent Adaptive_E-Learning_System -Stop Learning the Hard Way | Adaptive AI tutoring that reads your mind, adjusts difficulty instantly, and turns struggling into mastery. Each lesson evolves with YOUβ€”practice coding live, get instant hints, and watch your knowledge grow. +# Adaptive E-Learning System + +Adaptive tutoring that models what each learner knows, teaches at their level, and brings topics +back just before they are forgotten. + +- **Frontend**: React + Vite + Tailwind (Vercel), at https://adaptive-e-learning-system.vercel.app +- **Backend**: Flask API on a Hugging Face Space (Docker) +- **Agents**: LangGraph multi-agent graph with LangChain structured outputs (Gemini) +- **Learner model**: Bayesian Knowledge Tracing (online) plus a transformer knowledge-tracing model + trained on GPU and served on CPU through ONNX Runtime + +## Architecture + +``` +React (Vercel) ──Bearer token──► Flask API (HF Space, gunicorn gthread) + β”‚ + β”œβ”€β”€ Coordinator = LangGraph StateGraph + β”‚ START β†’ KnowledgeAgent (learner profile) + β”‚ β”œβ”€β–Ί TeachingAgent: strategy bandit β†’ structured lesson (LLM / cache / offline) + β”‚ β”œβ”€β–Ί AssessmentAgent: plan (target 70% success) β†’ question bank + β”‚ β”‚ β†Ί generate_questions (one LLM call, only when the bank runs short) + β”‚ β”œβ”€β–Ί TutorAgent: hint ladder (socratic β†’ conceptual β†’ direct) + β”‚ └─► RecommendationAgent: readiness, ZPD, spaced-repetition urgency + β”œβ”€β”€ Tutor chat = LangGraph MessagesState + SQLite checkpointer (memory per user Γ— topic) + β”œβ”€β”€ Learner model = BKT (persisted) + forgetting curve + transformer KT (ONNX) + └── SQLite (WAL): users, attempts, question bank, lesson cache, bandit posteriors +``` + +| Agent | Decides | How | +|---|---|---| +| Knowledge | What does the learner know right now? | BKT posterior per topic, exponential forgetting, transformer KT predictions of P(correct) for every topic Γ— difficulty | +| Teaching | How to teach this learner? | Expert rules provide the prior; a Thompson-sampling bandit learns from follow-up quiz results which strategy works per knowledge bucket | +| Assessment | Which questions, at what difficulty? | Difficulty mix chosen so predicted success β‰ˆ 70%; unseen bank items preferred and calibrated by empirical p-correct; server-side grading | +| Tutor | How much help to give? | Hint level escalates with attempts; the LLM phrases it using the learner's code, output and mastery | +| Recommendation | What next? | Prerequisite readiness gate, learning potential, zone of proximal development, review urgency, goals | + +## Knowledge-tracing results + +Trained on an RTX 5090 (`training/`). Metric: test AUC for predicting the next answer. + +**Real student data** (ASSISTments, standard DKVMN splits), used to validate the training harness: + +| Model | ASSIST2009 | ASSIST2015 | +|---|---|---| +| BKT (per-skill, grid-search fit) | 0.711 | 0.702 | +| DKT (LSTM) | **0.819** | **0.731** | +| Transformer KT (best of a 16-config sweep) | 0.810 | 0.727 | + +DKT matches published numbers. On these small datasets the transformer does not beat DKT, which is +consistent with public KT benchmarks. + +**App curriculum** (20 topics, 3 difficulties, time gaps; 7.15M interactions from a learner simulator +with prerequisites, ZPD learning and forgetting): + +| Model | Test AUC | +|---|---| +| Oracle (simulator's true probabilities, upper bound) | 0.719 | +| **Transformer KT, deployed (669k params, 2.7 MB ONNX)** | **0.693** | +| DKT (LSTM) | 0.689 | +| BKT | 0.654 | +| v1 heuristic tracker | 0.607 | + +The deployed model captures about 88% of the achievable discrimination above chance; the v1 heuristic captured about 49%. +The simulator is not real learner data. Retrain on real logs with +`--app-db data/database.db` once the app has users; the pipeline appends them to the training set. + +## Running locally + +```bash +# one isolated env for the whole project (GPU wheels bundle their own CUDA runtime; +# the system driver/CUDA are untouched) +conda env create -f environment.yml && conda activate elearn + +# backend (offline mode without a key: question bank + curriculum lessons) +cd backend && cp .env.example .env # add GEMINI_API_KEY and SECRET_KEY +SESSION_COOKIE_SECURE=false python app.py # http://localhost:7860 +pytest tests -q + +# frontend +cd frontend && npm install && npm run dev # http://localhost:3000 +``` + +Retrain the models (GPU): + +```bash +python training/train_kt.py --dataset assist2009 --model all # benchmark +python training/train_kt.py --dataset curriculum --model transformer \ + --students 100000 --d 128 --layers 3 --heads 4 --dropout 0.1 --export # production model β†’ backend/ml/artifacts +``` + +## Deployment + +- **HF Space**: built from the root `Dockerfile`. Set the secrets `SECRET_KEY` and `GEMINI_API_KEY` + (optional: `LLM_MODEL`). Enable persistent storage to keep the database across restarts; it is used + automatically when `/data` is mounted. +- **Vercel**: root `frontend/`, env `VITE_API_URL=https://sawabedarain-adaptive-elearning-backend.hf.space`. + +## API + +`POST /api/register` Β· `POST /api/login` Β· `GET /api/current-user` Β· `PUT /api/profile` +`GET /api/topics` Β· `POST /api/generate-lesson` Β· `POST /api/generate-quiz` Β· `POST /api/submit-answer` +`GET /api/progress-summary` Β· `GET /api/knowledge-states` Β· `GET /api/recommendations` Β· `GET /api/next-topic` +`GET /api/learning-path/` Β· `GET /api/review-queue` Β· `GET /api/study-tips` +`POST /api/check-code` (sandboxed subprocess) Β· `POST /api/ask-challenge-hint` +`POST /api/tutor/chat` Β· `GET|DELETE /api/tutor/history` Β· `GET /api/agent-status` Β· `GET /api/model-info` Β· `GET /api/health` diff --git a/backend/.env.example b/backend/.env.example index 52ab8b6d7190443a766d819c03c6f992a322f3a8..a16ae0c51260a2bb2d8922dd64c9d719094ff4ac 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -1,2 +1,12 @@ -GEMINI_API_KEY=your_api_key_here -SECRET_KEY=your-secret-key-here \ No newline at end of file +# Required in production: signs auth tokens (generate with: python -c "import secrets; print(secrets.token_hex(32))") +SECRET_KEY=change-me + +# LLM (Google Gemini via LangChain). Without a key the app runs in offline mode: +# question bank + curriculum-based lessons, rule-based hints. +GEMINI_API_KEY= +LLM_MODEL=gemini-2.5-flash + +# Optional +# DATA_DIR=/data # defaults to /data on HF persistent storage, else ../data +# CORS_ORIGINS=http://localhost:3000,https://adaptive-e-learning-system.vercel.app +# SESSION_COOKIE_SECURE=false # set false for plain-http local development diff --git a/backend/Dockerfile b/backend/Dockerfile index 24305aef7013cf8cc11eb917cc8e12663fa5cca5..f74fc133bccee8a1fea2fba907a05f972a4f6268 100644 --- a/backend/Dockerfile +++ b/backend/Dockerfile @@ -1,33 +1,21 @@ -# Use an official Python runtime as a parent image -FROM python:3.10-slim +# Standalone backend image (build context: backend/). The repo-root Dockerfile is the one HF Spaces uses. +FROM python:3.11-slim -# Set environment variables -ENV PYTHONDONTWRITEBYTECODE 1 -ENV PYTHONUNBUFFERED 1 -ENV PORT 7860 +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + PIP_NO_CACHE_DIR=1 \ + PORT=7860 \ + DATA_DIR=/app/data -# Set the working directory in the container -WORKDIR /app +RUN useradd -m -u 1000 user +WORKDIR /app/backend -# Install system dependencies (needed for some python packages like numpy/scikit-learn) -RUN apt-get update && apt-get install -y --no-install-recommends \ - build-essential \ - && rm -rf /var/lib/apt/lists/* - -# Copy the requirements file into the container COPY requirements.txt . +RUN pip install -r requirements.txt -# Install any needed packages specified in requirements.txt -RUN pip install --no-cache-dir -r requirements.txt - -# Copy the rest of the backend code -COPY . . +COPY --chown=user . . +RUN mkdir -p /app/data && chown -R user /app/data -# Create the data directory for SQLite if it doesn't exist -RUN mkdir -p /app/data - -# Expose the port the app runs on +USER user EXPOSE 7860 - -# Run the application -CMD ["gunicorn", "--bind", "0.0.0.0:7860", "--timeout", "120", "--workers", "1", "app:app"] +CMD ["gunicorn", "--bind", "0.0.0.0:7860", "--workers", "1", "--threads", "8", "--worker-class", "gthread", "--timeout", "180", "app:app"] diff --git a/backend/agent_communication/message_bus.py b/backend/agent_communication/message_bus.py deleted file mode 100644 index bebbde349fb7599d10c69f3e91f2239cb6336378..0000000000000000000000000000000000000000 --- a/backend/agent_communication/message_bus.py +++ /dev/null @@ -1,88 +0,0 @@ -from datetime import datetime -from models import db, AgentMessage -import json - -class AgentMessageBus: - """ - Central message bus for inter-agent communication. - Allows agents to subscribe to topics and send direct messages. - """ - - _instance = None - - def __new__(cls): - if cls._instance is None: - cls._instance = super(AgentMessageBus, cls).__new__(cls) - cls._instance.subscribers = {} # agent_id -> callback - return cls._instance - - def subscribe(self, agent_id, callback): - """ - Register an agent to receive messages. - - Args: - agent_id (str): The ID of the receiving agent. - callback (func): Function to call when message arrives. - """ - self.subscribers[agent_id] = callback - print(f"Agent {agent_id} subscribed to message bus.") - - def send_message(self, from_agent, to_agent, message_type, content): - """ - Send a message from one agent to another. - """ - # Create persistent record - try: - message = AgentMessage( - from_agent=from_agent, - to_agent=to_agent, - message_type=message_type, - content=content, - status='pending' - ) - # Use application context if running within request - if db.session: - db.session.add(message) - db.session.commit() - except Exception as e: - print(f"Warning: Could not save message to DB: {e}") - message = AgentMessage( - from_agent=from_agent, - to_agent=to_agent, - message_type=message_type, - content=content, - status='pending' - ) - - # Direct delivery if subscriber exists (Synchronous for now) - if to_agent in self.subscribers: - try: - response = self.subscribers[to_agent](message) - - # Update status - if db.session: - message.status = 'processed' - message.processed_at = datetime.utcnow() - db.session.commit() - - return response - except Exception as e: - print(f"Error delivering message to {to_agent}: {e}") - if db.session: - message.status = 'failed' - db.session.commit() - return None - else: - print(f"Agent {to_agent} not found or offline.") - return None - - def broadcast(self, from_agent, message_type, content): - """ - Send a message to all subscribed agents (except sender). - """ - responses = {} - for agent_id in self.subscribers: - if agent_id != from_agent: - response = self.send_message(from_agent, agent_id, message_type, content) - responses[agent_id] = response - return responses diff --git a/backend/agent_communication/protocols.py b/backend/agent_communication/protocols.py deleted file mode 100644 index 89a7ceec26d282cbfac8871f76163432cafd0d4b..0000000000000000000000000000000000000000 --- a/backend/agent_communication/protocols.py +++ /dev/null @@ -1,52 +0,0 @@ -class MessageProtocols: - """ - Defines standard message structures and types for agent communication. - Ensures all agents speak the same 'language'. - """ - - # Message Types - KNOWLEDGE_REQUEST = 'knowledge_request' - KNOWLEDGE_RESPONSE = 'knowledge_response' - LEARNING_COMPLETE = 'learning_complete' - CONTENT_REQUEST = 'content_request' - ASSESSMENT_RESULT = 'assessment_result' - - @staticmethod - def request_student_profile(user_id, topic_id=None): - """Teaching Agent -> Knowledge Agent""" - return { - 'type': MessageProtocols.KNOWLEDGE_REQUEST, - 'user_id': user_id, - 'topic_id': topic_id, - 'fields': ['knowledge_level', 'learning_style', 'weak_areas', 'frustration_level'] - } - - @staticmethod - def provide_student_profile(user_id, profile_data): - """Knowledge Agent -> Teaching Agent""" - return { - 'type': MessageProtocols.KNOWLEDGE_RESPONSE, - 'user_id': user_id, - 'profile': profile_data - } - - @staticmethod - def notify_assessment_complete(user_id, topic_id, score, details): - """Assessment Agent -> Knowledge Agent""" - return { - 'type': MessageProtocols.ASSESSMENT_RESULT, - 'user_id': user_id, - 'topic_id': topic_id, - 'score': score, - 'details': details - } - - @staticmethod - def request_content_generation(topic_id, content_type, difficulty): - """Coordinator -> Specialist Agent""" - return { - 'type': MessageProtocols.CONTENT_REQUEST, - 'topic_id': topic_id, - 'content_type': content_type, - 'difficulty': difficulty - } diff --git a/backend/agent_knowledge/__init__.py b/backend/agent_knowledge/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/backend/agent_knowledge/rules/__init__.py b/backend/agent_knowledge/rules/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/backend/agent_knowledge/rules/assessment_rules.py b/backend/agent_knowledge/rules/assessment_rules.py deleted file mode 100644 index 2cdf4f73916a803e59331521b27edc10eb7cf594..0000000000000000000000000000000000000000 --- a/backend/agent_knowledge/rules/assessment_rules.py +++ /dev/null @@ -1,87 +0,0 @@ -import json -import os -import random - -class AssessmentRuleEngine: - """ - Expert system for assessment decisions. - Selects questions and formats quizzes based on rules and templates. - """ - - def __init__(self, knowledge_base_path=None): - if knowledge_base_path is None: - base_dir = os.path.dirname(os.path.dirname(__file__)) - knowledge_base_path = os.path.join(base_dir, 'knowledge_bases', 'question_templates.json') - - self.question_templates = [] - self.rubrics = {} - self._load_knowledge_base(knowledge_base_path) - - def _load_knowledge_base(self, path): - try: - with open(path, 'r') as f: - data = json.load(f) - self.question_templates = data.get('question_templates', []) - self.rubrics = data.get('assessment_rubrics', {}) - except Exception as e: - print(f"Error loading assessment knowledge base: {e}") - - def select_question_types(self, knowledge_level, topic_difficulty): - """ - Determine the mix of question types/difficulties. - """ - mix = {"beginner": 0, "intermediate": 0, "advanced": 0} - - if knowledge_level < 0.3: - mix["beginner"] = 3 - mix["intermediate"] = 1 - elif knowledge_level < 0.7: - mix["beginner"] = 1 - mix["intermediate"] = 2 - mix["advanced"] = 1 - else: - mix["intermediate"] = 2 - mix["advanced"] = 3 - - return mix - - def get_template_for_topic(self, topic_name, difficulty): - """ - Find a question template suitable for the topic and difficulty. - """ - candidates = [] - for t in self.question_templates: - # Check if template is applicable to this topic (simple keyword match for now) - # In a real system, this would be a more robust tag matching - is_applicable = "all" in t['applicable_topics'] - if not is_applicable: - for keyword in t['applicable_topics']: - if keyword in topic_name.lower(): - is_applicable = True - break - - if is_applicable: - candidates.append(t) - - if not candidates: - return None - - return random.choice(candidates) - - def formulate_question_prompt(self, template, topic_name, difficulty): - """ - Use a template to create a specific prompt for the LLM to fill. - This reduces the LLM's work to just filling blanks/generating code. - """ - modifier = template['difficulty_modifiers'].get(difficulty, "Standard") - - prompt = f""" - Generate a specific question about "{topic_name}" using this pattern: - "{template['pattern']}" - - Constraint: {modifier} - Cognitive Level: {template['cognitive_level']} - - Return the Code Snippet (if applicable), Options, Correct Answer, and Explanation. - """ - return prompt diff --git a/backend/agent_knowledge/rules/knowledge_rules.py b/backend/agent_knowledge/rules/knowledge_rules.py deleted file mode 100644 index 6d6f2dd6c5ec652868af9dfa4552b79b4c225e20..0000000000000000000000000000000000000000 --- a/backend/agent_knowledge/rules/knowledge_rules.py +++ /dev/null @@ -1,47 +0,0 @@ -import math -from datetime import datetime - -class KnowledgeRuleEngine: - """ - Expert system for knowledge tracking decisions. - """ - - def calculate_forgetting(self, last_practice_date, current_knowledge): - """ - Apply Ebbinghaus forgetting curve. - """ - if not last_practice_date: - return current_knowledge - - days_elapsed = (datetime.utcnow() - last_practice_date).days - - if days_elapsed <= 0: - return current_knowledge - - # R = e^(-t/S) - # Stability (S) increases with knowledge strength - stability = max(1, current_knowledge * 30) - retention = math.exp(-days_elapsed / stability) - - return current_knowledge * retention - - def predict_growth(self, current_knowledge, is_correct, difficulty): - """ - Predict new knowledge level after an interaction. - """ - learning_rate = 0.1 - difficulty_weight = 1.0 - - if difficulty == "advanced": - difficulty_weight = 1.2 - elif difficulty == "beginner": - difficulty_weight = 0.8 - - if is_correct: - # Logarithmic growth: harder to improve as you get closer to 1.0 - growth = learning_rate * difficulty_weight * (1 - current_knowledge) - return min(1.0, current_knowledge + growth) - else: - # Penalty is smaller than growth - penalty = learning_rate * 0.5 * current_knowledge - return max(0.0, current_knowledge - penalty) diff --git a/backend/agent_knowledge/rules/recommendation_rules.py b/backend/agent_knowledge/rules/recommendation_rules.py deleted file mode 100644 index a04f403a8375713d1f20e2a93e9645185fb747c7..0000000000000000000000000000000000000000 --- a/backend/agent_knowledge/rules/recommendation_rules.py +++ /dev/null @@ -1,44 +0,0 @@ -class RecommendationRuleEngine: - """ - Expert system for recommendation decisions. - """ - - def score_topic(self, topic, user_knowledge_map): - """ - Score a topic for recommendation suitability. - Returns a score (higher is better). - """ - score = 0 - current_knowledge = user_knowledge_map.get(topic.id, 0) - - # Rule 1: Don't recommend mastered topics (unless for review) - if current_knowledge > 0.85: - return -1 - - # Rule 2: Prerequisites must be met - if not self._check_prerequisites(topic, user_knowledge_map): - return -10 # Blocked - - # Rule 3: Prioritize active topics - if 0 < current_knowledge < 0.7: - score += 5 - - # Rule 4: Beginner topics get boost if nothing started - if current_knowledge == 0 and topic.difficulty == "beginner": - score += 3 - - return score - - def _check_prerequisites(self, topic, knowledge_map): - if not topic.prerequisites: - return True - - if isinstance(topic.prerequisites, str): - prereq_ids = [int(p) for p in topic.prerequisites.split(',') if p.strip()] - else: - prereq_ids = [] - - for pid in prereq_ids: - if knowledge_map.get(pid, 0) < 0.6: - return False - return True diff --git a/backend/agents/__init__.py b/backend/agents/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/backend/agents/assessment_agent.py b/backend/agents/assessment_agent.py index 167fa25de949ed8f822ce62563ac97efabb35fdd..d8751861d23895f25b3e8771e159ff3dd8e95813 100644 --- a/backend/agents/assessment_agent.py +++ b/backend/agents/assessment_agent.py @@ -1,192 +1,119 @@ -import json """ -Assessment Agent - Autonomous quiz generation and evaluation +AssessmentAgent + decide (plan_quiz): choose quiz length and difficulty mix so predicted success ~= target + ("desirable difficulty"), using the KT model's per-difficulty predictions + act (assemble_quiz): draw questions from the bank (no LLM), preferring unseen, well-calibrated items + generate_questions: only when the bank runs short β€” ONE structured LLM call, validated + deduplicated, + then loop back to assemble (a LangGraph cycle, max 2 rounds) + finalize_quiz: top-up from already-seen items if still short, then build the payload """ -from .base_agent import BaseAgent -from llm_service import LLMService -from agent_knowledge.rules.assessment_rules import AssessmentRuleEngine -from agent_communication.message_bus import AgentMessageBus -from datetime import datetime +import math +import random -class AssessmentAgent(BaseAgent): - """ - Autonomous agent responsible for: - - Generating adaptive quizzes - - Evaluating answers - - Adjusting question difficulty - - Providing detailed feedback - """ - - def __init__(self): - super().__init__("AA-001", "AssessmentAgent") - self.llm_service = LLMService() - self.rule_engine = AssessmentRuleEngine() - self.message_bus = AgentMessageBus() - self.quizzes_generated = 0 - self.questions_evaluated = 0 - self.difficulty_adjustments = 0 - - def perceive(self, student_state): - """ - Perceive student's quiz context - - Args: - student_state: object with student's current state (e.g., knowledge_level) - """ - self.update_state("perceiving") - self.log(f"Perceiving assessment needs for user {student_state.user_id}") - - self.user_id = student_state.user_id - self.topic_id = student_state.topic_id - self.knowledge_level = student_state.knowledge_level - self.recent_performance = student_state.recent_performance - self.quiz_type = student_state.quiz_type - - # Logic to determine number of questions could be more dynamic - self.num_questions = 3 if self.knowledge_level < 0.5 else 5 - return self.state - - def decide(self): - """ - Autonomous decisions: - - What difficulty level for questions? - - How many questions? - - Question types (MCQ, coding, etc.) - - Focus areas - """ - self.update_state("deciding") - - # Decide on the mix of questions (difficulty, type) - self.question_mix = self.rule_engine.select_question_types( - self.knowledge_level, - "intermediate" # topic difficulty placeholder - ) - self.log(f"Decided question mix: {self.question_mix}") - return self - - def act(self, topic, prompt=None): - """ - Execute: Generate adaptive quiz - """ - self.update_state("acting") - self.log(f"Generating quiz for topic: {topic.name}") - - if not topic: - self.log("Topic not found", "error") - return {"error": "Topic not found"} - - questions = [] - try: - # 1. Try to generate questions from templates first (Rule-Based) - for difficulty, count in self.question_mix.items(): - for _ in range(count): - template = self.rule_engine.get_template_for_topic(topic.name, difficulty) - if template: - # Use LLM just to fill the template (cheaper/faster than full gen) - # In future, fetch from ContentLibrary DB directly - q_prompt = self.rule_engine.formulate_question_prompt( - template, topic.name, difficulty - ) - # We still use LLM service but with a very specific prompt - # This bridges the gap until we have a full static DB - generated = self.llm_service.generate_quiz_with_prompt( - topic.name, 1, custom_prompt=q_prompt - ) - if generated: - questions.extend(generated) - - # 2. Fallback or Fill remaining - if len(questions) < self.num_questions: - needed = self.num_questions - len(questions) - self.log(f"Template generation insufficient, requesting {needed} from LLM fallback.") - fallback_qs = self.llm_service.generate_quiz_with_prompt( - topic.name, needed, custom_prompt=prompt - ) - if fallback_qs: - questions.extend(fallback_qs) +from langchain_core.messages import HumanMessage, SystemMessage - # 3. Notify Knowledge Agent of new assessment (simulated) - # self.message_bus.send_message(...) - - self.quizzes_generated += 1 - self.log(f"Quiz generated successfully (Total: {self.quizzes_generated})") - - # Store in memory - self.memory.append({ - "action": "quiz_generated", - "topic": topic.name, - "num_questions": self.num_questions, - "difficulty_mix": self.difficulty_mix, - "user_id": self.user_id - }) - - self.update_state("completed") - - return { - "questions": quiz_questions, - "metadata": { - "difficulty_mix": self.difficulty_mix, - "focus_areas": self.focus_areas, - "agent": self.name, - "generated_at": datetime.utcnow().isoformat() - } - } - - except Exception as e: - self.log(f"Error generating quiz: {str(e)}", "error") - self.update_state("error") - return {"error": str(e)} - - def evaluate_answer(self, question, user_answer, correct_answer, context): - """ - Autonomous answer evaluation with detailed feedback - - Args: - question: str - user_answer: str - correct_answer: str - context: dict with topic info - """ - self.update_state("evaluating") - self.log(f"Evaluating answer: {user_answer} vs {correct_answer}") - - is_correct = user_answer == correct_answer - self.questions_evaluated += 1 - - # Generate intelligent feedback - feedback_prompt = f""" - Question: {question} - Student answered: {user_answer} - Correct answer: {correct_answer} - Result: {"Correct" if is_correct else "Incorrect"} - - Provide encouraging, educational feedback (2-3 sentences): - 1. If correct: Explain why and reinforce the concept - 2. If incorrect: Explain the misconception and guide to correct understanding - - Be supportive and educational. - """ - - try: - feedback = self.llm_service.model.generate_content(feedback_prompt).text - except: - feedback = "Review the concept and try again!" if not is_correct else "Great job!" - - self.log(f"Answer evaluated. Correct: {is_correct}") - - return { - "is_correct": is_correct, - "feedback": feedback, - "agent": self.name, - "evaluated_at": datetime.utcnow().isoformat() - } - - def get_statistics(self): - """Return agent statistics""" - return { - "agent": self.name, - "quizzes_generated": self.quizzes_generated, - "questions_evaluated": self.questions_evaluated, - "state": self.state, - "memory_size": len(self.memory) - } \ No newline at end of file +from models import QuestionBank, Topic, db +from services import content + +from .metrics import tracked +from .schemas import Quiz + +MAX_GENERATION_ROUNDS = 2 +EXTRA_QUESTIONS = 3 # grow the bank a little beyond the immediate shortfall + + +def allocate(weights, n): + """Largest-remainder allocation of n slots proportional to weights.""" + total = sum(weights.values()) or 1.0 + raw = {k: n * w / total for k, w in weights.items()} + alloc = {k: int(math.floor(v)) for k, v in raw.items()} + for k in sorted(raw, key=lambda k: raw[k] - alloc[k], reverse=True)[: n - sum(alloc.values())]: + alloc[k] += 1 + return alloc + + +def make_nodes(ctx): + cfg = ctx.config + + @tracked('assessment') + def plan_quiz(state): + tp = state['profile']['topics'].get(state['topic_id'], {}) + pred = tp.get('predicted_success') or {'beginner': 0.7, 'intermediate': 0.55, 'advanced': 0.4} + practice = tp.get('practice_count', 0) + n = cfg.QUIZ_SIZE_MIN if practice < 5 else (cfg.QUIZ_SIZE_MAX if tp.get('effective_mastery', 0) > 0.7 else 5) + target = cfg.TARGET_SUCCESS_RATE + # Relative weighting: the difficulty whose predicted success is closest to the target dominates, + # even when every level is far from it (e.g. a brand-new learner). + closest = min(abs(p - target) for p in pred.values()) + weights = {d: math.exp(-(abs(p - target) - closest) / 0.07) for d, p in pred.items()} + mix = allocate(weights, n) + expected = sum(pred[d] * c for d, c in mix.items()) / n + return {'quiz_plan': {'num_questions': n, 'difficulty_mix': mix, 'target_success': target, + 'expected_success': round(expected, 3), 'predicted_success': pred}, + 'generation_rounds': state.get('generation_rounds', 0)} + + @tracked('assessment') + def assemble_quiz(state): + plan = state['quiz_plan'] + rows, shortfall = content.pick_questions(state['user_id'], state['topic_id'], plan['difficulty_mix'], + target_p=plan['target_success']) + return {'quiz': {'question_ids': [q.id for q in rows], 'shortfall': shortfall}} + + def _generation_prompt(topic, shortfall, profile): + existing = [q.question for q in QuestionBank.query.filter_by(topic_id=topic.id).limit(40)] + weak = [w['name'] for w in profile.get('weak_topics', [])][:3] + templates = '\n'.join(f"- {t['id']} ({t['cognitive_level']}): {t['pattern'].splitlines()[0]}" + for t in ctx.question_templates) + wanted = ', '.join(f'{c} {d}' for d, c in shortfall.items()) + total = sum(shortfall.values()) + EXTRA_QUESTIONS + return [ + SystemMessage('You are an assessment designer who writes unambiguous multiple-choice questions ' + 'with exactly one correct answer and plausible distractors based on common misconceptions.'), + HumanMessage( + f"Write {total} multiple-choice questions on '{topic.name}': {topic.description}\n" + f"Difficulty counts needed: {wanted} (put the {EXTRA_QUESTIONS} extra at intermediate).\n" + f"Cover these concepts, spreading questions across them: {', '.join(topic.key_concepts or [])}.\n" + f"Vary question types using these templates:\n{templates}\n" + f"The learner is currently weak in: {', '.join(weak) or 'n/a'}.\n" + f"Do NOT repeat or paraphrase any of these existing questions:\n" + + '\n'.join(f'- {q}' for q in existing[:30]) + + '\nRandomise which letter is correct. Keep code snippets short and put them inside the question text.' + ), + ] + + @tracked('assessment') + def generate_questions(state): + topic = db.session.get(Topic, state['topic_id']) + rounds = state.get('generation_rounds', 0) + 1 + result = ctx.llm.structured(Quiz, _generation_prompt(topic, state['quiz']['shortfall'], state['profile'])) + if result is None: + return {'generation_rounds': MAX_GENERATION_ROUNDS, 'errors': ['question_generation_failed']} + added = content.add_questions(topic.id, [q.model_dump() for q in result.questions], source='llm') + return {'generation_rounds': rounds if added else MAX_GENERATION_ROUNDS} + + @tracked('assessment') + def finalize_quiz(state): + plan, quiz = state['quiz_plan'], state['quiz'] + ids = list(quiz['question_ids']) + missing = plan['num_questions'] - len(ids) + if missing > 0: + ids += [q.id for q in content.fill_from_any(state['user_id'], state['topic_id'], set(ids), missing)] + rows = {q.id: q for q in QuestionBank.query.filter(QuestionBank.id.in_(ids)).all()} if ids else {} + ordered = [rows[i] for i in ids if i in rows] + order = {'beginner': 0, 'intermediate': 1, 'advanced': 2} + ordered.sort(key=lambda q: (order.get(q.difficulty, 1), random.random())) # warm-up first + for q in ordered: + q.times_served = (q.times_served or 0) + 1 + return {'quiz': {'questions': [q.to_public_dict() for q in ordered], + 'metadata': {**plan, 'from_bank': len(quiz['question_ids']), + 'generation_rounds': state.get('generation_rounds', 0)}}} + + def route_after_assemble(state): + short = state['quiz'].get('shortfall') + if short and ctx.llm.available and state.get('generation_rounds', 0) < MAX_GENERATION_ROUNDS: + return 'generate_questions' + return 'finalize_quiz' + + nodes = {'plan_quiz': plan_quiz, 'assemble_quiz': assemble_quiz, + 'generate_questions': generate_questions, 'finalize_quiz': finalize_quiz} + return nodes, route_after_assemble diff --git a/backend/agents/base_agent.py b/backend/agents/base_agent.py deleted file mode 100644 index 2aa0c272619fd9313740e6299ad9d399326d0b87..0000000000000000000000000000000000000000 --- a/backend/agents/base_agent.py +++ /dev/null @@ -1,73 +0,0 @@ -""" -Base Agent Class - All agents inherit from this -""" -from abc import ABC, abstractmethod -import logging -from datetime import datetime - -logging.basicConfig(level=logging.INFO) - -class StudentState: - """Standardized student state object for agent perception""" - def __init__(self, user_id, **kwargs): - self.user_id = user_id - for key, value in kwargs.items(): - setattr(self, key, value) - -class BaseAgent(ABC): - """Base class for all autonomous agents""" - - def __init__(self, agent_id, name): - self.agent_id = agent_id - self.name = name - self.state = "idle" - self.memory = [] - self.logger = logging.getLogger(f"Agent-{name}") - self.created_at = datetime.utcnow() - - def log(self, message, level="info"): - """Log agent activities""" - log_entry = { - "timestamp": datetime.utcnow().isoformat(), - "agent": self.name, - "message": message, - "state": self.state - } - self.memory.append(log_entry) - - if level == "info": - self.logger.info(f"[{self.name}] {message}") - elif level == "error": - self.logger.error(f"[{self.name}] {message}") - elif level == "warning": - self.logger.warning(f"[{self.name}] {message}") - - def update_state(self, new_state): - """Update agent state""" - old_state = self.state - self.state = new_state - self.log(f"State transition: {old_state} β†’ {new_state}") - - @abstractmethod - def perceive(self, environment): - """Perceive the environment - to be implemented by subclasses""" - pass - - @abstractmethod - def decide(self): - """Make autonomous decisions - to be implemented by subclasses""" - pass - - @abstractmethod - def act(self): - """Execute actions - to be implemented by subclasses""" - pass - - def get_memory(self, limit=10): - """Retrieve recent memory""" - return self.memory[-limit:] - - def clear_memory(self): - """Clear agent memory""" - self.memory = [] - self.log("Memory cleared") \ No newline at end of file diff --git a/backend/agents/coordinator_agent.py b/backend/agents/coordinator_agent.py deleted file mode 100644 index 69629aacb031addf0e77a7d2e45df78daa7c1524..0000000000000000000000000000000000000000 --- a/backend/agents/coordinator_agent.py +++ /dev/null @@ -1,275 +0,0 @@ -""" -Coordinator Agent - Orchestrates all other agents -""" -from agents.base_agent import BaseAgent, StudentState -from agents.teaching_agent import TeachingAgent -from agents.assessment_agent import AssessmentAgent -from agents.knowledge_agent import KnowledgeAgent -from agents.tutor_agent import TutorAgent -from agents.recommendation_agent import RecommendationAgent -from datetime import datetime -import json - -class CoordinatorAgent(BaseAgent): - """ - Master agent that coordinates all other agents - """ - - def __init__(self): - super().__init__("CA-001", "CoordinatorAgent") - - # Initialize all sub-agents - self.teaching_agent = TeachingAgent() - self.assessment_agent = AssessmentAgent() - self.knowledge_agent = KnowledgeAgent() - self.tutor_agent = TutorAgent() - self.recommendation_agent = RecommendationAgent() - - self.tasks_coordinated = 0 - - self.log("Coordinator initialized with 5 sub-agents") - - def perceive(self, environment): - """ - Perceive global learning environment - """ - self.update_state("perceiving") - self.log(f"Coordinating agents for task: {environment.get('task')}") - - self.task = environment.get('task') - self.user_id = environment.get('user_id') - self.context = environment.get('context', {}) - - return self - - def decide(self): - """ - Decide which agents to activate - """ - self.update_state("deciding") - - # Route to appropriate agents based on task - self.active_agents = [] - - if self.task == "generate_lesson": - self.active_agents = [self.teaching_agent, self.knowledge_agent] - self.workflow = "sequential" # Knowledge first, then teaching - - elif self.task == "generate_quiz": - self.active_agents = [self.knowledge_agent, self.assessment_agent] - self.workflow = "sequential" - - elif self.task == "evaluate_answer": - self.active_agents = [self.assessment_agent, self.knowledge_agent] - self.workflow = "sequential" - - elif self.task == "provide_hint": - self.active_agents = [self.tutor_agent] - self.workflow = "single" - - elif self.task == "recommend_topic": - self.active_agents = [self.knowledge_agent, self.recommendation_agent] - self.workflow = "sequential" - - elif self.task == "full_learning_session": - # Complex workflow involving all agents - self.active_agents = [ - self.knowledge_agent, - self.recommendation_agent, - self.teaching_agent, - self.assessment_agent, - self.tutor_agent - ] - self.workflow = "complex" - - else: - self.log(f"Unknown task: {self.task}", "warning") - self.active_agents = [] - self.workflow = "none" - - self.log(f"Activating {len(self.active_agents)} agents in {self.workflow} workflow") - - return self - - def act(self): - """ - Execute coordinated agent workflow - """ - self.update_state("acting") - self.log("Executing coordinated workflow...") - - results = {} - - try: - # Create standardized student state - student_state = StudentState( - user_id=self.user_id, - **self.context - ) - - # Fetch Topic object if ID is present - current_topic = None - if self.context.get('topic_id'): - from models import Topic - current_topic = Topic.query.get(self.context['topic_id']) - - if self.workflow == "single": - # Single agent execution - agent = self.active_agents[0] - agent.perceive(student_state) - agent.decide() - - # Handle specific agent signatures - if isinstance(agent, TeachingAgent): - results = agent.act(topic=current_topic) - elif isinstance(agent, AssessmentAgent): - results = agent.act(topic=current_topic) - elif isinstance(agent, TutorAgent): - results = agent.act(prompt=self.context.get('question')) - elif isinstance(agent, KnowledgeAgent): - # KnowledgeAgent act requires specific action type usually - # For general single execution, we assume a state update or status check - action = self.context.get('action_type', 'get_status') - results = agent.act(self.user_id, action_type=action, **self.context) - elif isinstance(agent, RecommendationAgent): - results = agent.act() - - elif self.workflow == "sequential": - # Sequential agent execution - # Note: This generic loop is hard to maintain with diverse signatures. - # We will customize it based on the specific sequence defined in decide() - - for i, agent in enumerate(self.active_agents): - self.log(f"Step {i+1}: Executing {agent.name}") - - # Update state with results from previous steps - for key, val in results.items(): - setattr(student_state, key, val) - - agent.perceive(student_state) - agent.decide() - - agent_result = {} - if isinstance(agent, TeachingAgent): - # Teaching agent needs a topic. If not in context, maybe from previous agent? - topic_to_teach = current_topic - if 'next_best' in results: # From RecommendationAgent - # Mocking topic object from result dict if needed, or fetching DB - from models import Topic - topic_to_teach = Topic.query.get(results['next_best']['topic_id']) - - if topic_to_teach: - agent_result = agent.act(topic=topic_to_teach) - else: - self.log("TeachingAgent needs a topic but none provided", "error") - - elif isinstance(agent, AssessmentAgent): - agent_result = agent.act(topic=current_topic) - elif isinstance(agent, KnowledgeAgent): - # Sequential usually implies updating state after something - if 'quiz_score' in self.context: - agent_result = agent.act(self.user_id, 'update_state', - topic_id=current_topic.id, - is_correct=self.context.get('is_correct'), - difficulty=current_topic.difficulty) - else: - agent_result = agent.act(self.user_id, 'get_weak_areas') - - elif isinstance(agent, RecommendationAgent): - agent_result = agent.act() - - results[agent.name] = agent_result - - elif self.workflow == "complex": - results = self._execute_complex_workflow(student_state, current_topic) - - self.tasks_coordinated += 1 - self.log(f"Workflow completed successfully") - self.update_state("completed") - - return { - "success": True, - "results": results, - "workflow": self.workflow - } - - except Exception as e: - self.log(f"Workflow error: {str(e)}", "error") - return {"success": False, "error": str(e)} - - def _execute_complex_workflow(self, student_state, current_topic): - """ - Execute complex multi-agent workflow - """ - results = {} - - # Step 1: Knowledge Agent analyzes current state - self.log("Complex workflow - Step 1: Knowledge analysis") - self.knowledge_agent.perceive(student_state) - # No decide/act needed for just analysis in this flow, but let's get weak areas - knowledge_result = self.knowledge_agent.act(self.user_id, 'get_weak_areas') - results['knowledge_analysis'] = knowledge_result - - # Step 2: Recommendation Agent suggests path - self.log("Complex workflow - Step 2: Path recommendation") - self.recommendation_agent.perceive(student_state) - self.recommendation_agent.decide() - recommendation_result = self.recommendation_agent.act() - results['recommendations'] = recommendation_result - - # Step 3: Teaching Agent creates lesson - if recommendation_result.get('next_best'): - next_topic_data = recommendation_result['next_best'] - from models import Topic - next_topic = Topic.query.get(next_topic_data['topic_id']) - - self.log("Complex workflow - Step 3: Lesson generation") - # Update student state with specific topic context - student_state.topic_id = next_topic.id - student_state.knowledge_level = next_topic_data.get('current_knowledge', 0) - - self.teaching_agent.perceive(student_state) - self.teaching_agent.decide() - teaching_result = self.teaching_agent.act(topic=next_topic) - results['lesson'] = teaching_result - - # Step 4: Assessment Agent prepares quiz for this new topic - self.log("Complex workflow - Step 4: Assessment preparation") - self.assessment_agent.perceive(student_state) - self.assessment_agent.decide() - assessment_result = self.assessment_agent.act(topic=next_topic) - results['assessment'] = assessment_result - - return results - - def get_agent_status(self): - """ - Get status of all agents - """ - return { - "coordinator": self.get_statistics(), - "sub_agents": { - "teaching": self.teaching_agent.get_statistics(), - "assessment": self.assessment_agent.get_statistics(), - "knowledge": self.knowledge_agent.get_statistics(), - "tutor": self.tutor_agent.get_statistics(), - "recommendation": self.recommendation_agent.get_statistics() - }, - "total_memory": sum([ - len(self.teaching_agent.memory), - len(self.assessment_agent.memory), - len(self.knowledge_agent.memory), - len(self.tutor_agent.memory), - len(self.recommendation_agent.memory) - ]) - } - - def get_statistics(self): - """Return coordinator statistics""" - return { - "agent": self.name, - "tasks_coordinated": self.tasks_coordinated, - "state": self.state, - "active_sub_agents": len(self.active_agents) if hasattr(self, 'active_agents') else 0, - "memory_size": len(self.memory) - } \ No newline at end of file diff --git a/backend/agents/graph.py b/backend/agents/graph.py new file mode 100644 index 0000000000000000000000000000000000000000..24bafdea7574302fca3f637a58d85fd8711e3505 --- /dev/null +++ b/backend/agents/graph.py @@ -0,0 +1,83 @@ +""" +CoordinatorAgent as a LangGraph StateGraph. + + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Ί recommend ──(full session)──┐ + START ─► profile_learner┼──────────────► provide_hint ─► END β”‚ + (KnowledgeAgent) β”œβ”€β–Ί select_strategy ─► teach ─(full)─┐ β”‚ + β”‚ β–² (TeachingAgent) β”‚ β”‚ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”˜ + └─► plan_quiz ─► assemble_quiz ──► finalize_quiz ─► END + (AssessmentAgent) β”‚ β–² + β–Ό β”‚ (bank short & LLM available, ≀2 rounds) + generate_questions +""" +import time + +from langgraph.graph import END, START, StateGraph + +from . import assessment_agent, knowledge_agent, recommendation_agent, teaching_agent, tutor_agent +from .metrics import METRICS +from .state import LearningState + +TASK_ENTRY = { + 'generate_lesson': 'select_strategy', + 'generate_quiz': 'plan_quiz', + 'provide_hint': 'provide_hint', + 'recommend_topic': 'recommend', + 'full_learning_session': 'recommend', +} + + +def build_graph(ctx): + g = StateGraph(LearningState) + nodes = {} + nodes.update(knowledge_agent.make_nodes(ctx)) + nodes.update(teaching_agent.make_nodes(ctx)) + assessment_nodes, route_after_assemble = assessment_agent.make_nodes(ctx) + nodes.update(assessment_nodes) + nodes.update(tutor_agent.make_nodes(ctx)) + nodes.update(recommendation_agent.make_nodes(ctx)) + for name, fn in nodes.items(): + g.add_node(name, fn) + + g.add_edge(START, 'profile_learner') + g.add_conditional_edges('profile_learner', lambda s: TASK_ENTRY.get(s['task'], END), + list(set(TASK_ENTRY.values())) + [END]) + g.add_conditional_edges('recommend', + lambda s: 'select_strategy' if s['task'] == 'full_learning_session' and s.get('topic_id') else END, + ['select_strategy', END]) + g.add_edge('select_strategy', 'teach') + g.add_conditional_edges('teach', lambda s: 'plan_quiz' if s['task'] == 'full_learning_session' else END, + ['plan_quiz', END]) + g.add_edge('plan_quiz', 'assemble_quiz') + g.add_conditional_edges('assemble_quiz', route_after_assemble, ['generate_questions', 'finalize_quiz']) + g.add_edge('generate_questions', 'assemble_quiz') + g.add_edge('finalize_quiz', END) + g.add_edge('provide_hint', END) + return g.compile() + + +class Coordinator: + """Thin facade used by the Flask routes.""" + + def __init__(self, ctx): + self.ctx = ctx + self.graph = build_graph(ctx) + + def run(self, task, user_id, topic_id=None, **request): + if task not in TASK_ENTRY: + raise ValueError(f'Unknown task: {task}') + METRICS.start('coordinator') + t0 = time.perf_counter() + ok = True + try: + return self.graph.invoke({'task': task, 'user_id': user_id, 'topic_id': topic_id, + 'request': request, 'trace': [], 'errors': []}) + except Exception: + ok = False + raise + finally: + METRICS.finish('coordinator', int((time.perf_counter() - t0) * 1000), ok=ok, note=task) + + def mermaid(self): + return self.graph.get_graph().draw_mermaid() diff --git a/backend/agents/init.py b/backend/agents/init.py deleted file mode 100644 index 91296b66e0b8ad8eab2eedb3d5caa8851a7cd7b6..0000000000000000000000000000000000000000 --- a/backend/agents/init.py +++ /dev/null @@ -1,21 +0,0 @@ -""" -Multi-Agent System for Adaptive E-Learning -""" - -from agents.base_agent import BaseAgent -from agents.teaching_agent import TeachingAgent -from agents.assessment_agent import AssessmentAgent -from agents.knowledge_agent import KnowledgeAgent -from agents.tutor_agent import TutorAgent -from agents.recommendation_agent import RecommendationAgent -from agents.coordinator_agent import CoordinatorAgent - -__all__ = [ - 'BaseAgent', - 'TeachingAgent', - 'AssessmentAgent', - 'KnowledgeAgent', - 'TutorAgent', - 'RecommendationAgent', - 'CoordinatorAgent' -] \ No newline at end of file diff --git a/backend/agents/knowledge_agent.py b/backend/agents/knowledge_agent.py index 5e720c4b5757114fdd474718a05bafcd1688bf9d..dcd7698f8b338b579808f3b600607068009c74bb 100644 --- a/backend/agents/knowledge_agent.py +++ b/backend/agents/knowledge_agent.py @@ -1,216 +1,11 @@ +"""KnowledgeAgent: builds the learner model every other agent conditions on.""" +from .metrics import tracked -""" -Knowledge Agent - Autonomous knowledge state management -""" -import json -from .base_agent import BaseAgent -from knowledge_tracker import KnowledgeTracker -from agent_knowledge.rules.knowledge_rules import KnowledgeRuleEngine -from models import db, KnowledgeState -import math -from datetime import datetime, timedelta -class KnowledgeAgent(BaseAgent): - """ - Autonomous agent responsible for: - - Tracking knowledge evolution - - Predicting future performance - - Identifying knowledge gaps - - Suggesting review topics - """ - - def __init__(self): - super().__init__("KA-001", "KnowledgeAgent") - self.tracker = KnowledgeTracker() - self.rule_engine = KnowledgeRuleEngine() - self.predictions_made = 0 - self.updates_performed = 0 - - def perceive(self, student_state): - """ - Perceive student's learning state - """ - self.update_state("perceiving") - self.user_id = getattr(student_state, 'user_id', None) - self.log(f"Perceiving knowledge state for user {self.user_id}") - - self.topic_id = getattr(student_state, 'topic_id', None) - - # Get all knowledge states - if self.user_id: - self.knowledge_states = KnowledgeState.query.filter_by( - user_id=self.user_id - ).all() - else: - self.knowledge_states = [] - - self.log(f"Found {len(self.knowledge_states)} knowledge states") - - return self - - def decide(self): - """ - Autonomous decisions: - - Which topics need review? - - What's the optimal learning path? - - Are there knowledge gaps? - """ - self.update_state("deciding") - - # Decision 1: Apply forgetting curves - topics_needing_review = [] - for state in self.knowledge_states: - days_since_practice = (datetime.utcnow() - state.last_practiced).days - - if days_since_practice > 7 and state.knowledge_level > 0.3: - topics_needing_review.append({ - 'topic_id': state.topic_id, - 'days_since': days_since_practice, - 'current_level': state.knowledge_level, - 'priority': days_since_practice * (1 - state.knowledge_level) - }) - - # Sort by priority - topics_needing_review.sort(key=lambda x: x['priority'], reverse=True) - self.review_recommendations = topics_needing_review[:3] - - # Decision 2: Identify knowledge gaps - self.knowledge_gaps = [ - state for state in self.knowledge_states - if 0 < state.knowledge_level < 0.4 - ] - - # Decision 3: Predict next knowledge level - if self.topic_id: - self.predicted_next_level = self._predict_knowledge_growth(self.topic_id) - else: - self.predicted_next_level = None - - self.log(f"Decisions: {len(self.review_recommendations)} topics need review, " - f"{len(self.knowledge_gaps)} knowledge gaps found") - - return self - - def _predict_knowledge_growth(self, topic_id): - """Predict knowledge growth based on learning patterns""" - state = KnowledgeState.query.filter_by( - user_id=self.user_id, - topic_id=topic_id - ).first() - - if not state: - return 0.15 # Expected growth for new topic - - # Predict based on practice frequency and current level - if state.practice_count > 5: - # Experienced learner - slower growth - growth = 0.1 * (1 - state.knowledge_level) - else: - # New learner - faster initial growth - growth = 0.15 * (1 - state.knowledge_level) - - predicted = min(1.0, state.knowledge_level + growth) - self.predictions_made += 1 - - self.log(f"Predicted knowledge growth: {state.knowledge_level:.2f} β†’ {predicted:.2f}") - - return predicted - - def act(self, user_id=None, action_type="monitoring", **kwargs): - """ - Execute: Update knowledge states and provide recommendations - """ - self.update_state("acting") - - if user_id: - self.user_id = user_id - - # Dispatch based on action type - if action_type == 'update_state': - return self.update_knowledge_from_quiz( - kwargs.get('topic_id'), - kwargs.get('is_correct'), - kwargs.get('difficulty') - ) - - # Default / Monitoring / get_weak_areas logic - self.log(f"performing {action_type}...") - - # Apply forgetting curves to all states - updated_states = [] - for state in self.knowledge_states: - days_since = (datetime.utcnow() - state.last_practiced).days - - if days_since > 0: - # Apply exponential forgetting - forgetting_factor = math.exp(-0.05 * days_since) - old_level = state.knowledge_level - state.knowledge_level *= forgetting_factor - - if abs(old_level - state.knowledge_level) > 0.01: - updated_states.append({ - 'topic_id': state.topic_id, - 'old_level': old_level, - 'new_level': state.knowledge_level, - 'decay': old_level - state.knowledge_level - }) - self.updates_performed += 1 - - # Commit updates - if updated_states: - db.session.commit() - - self.log(f"Updated {len(updated_states)} knowledge states") - self.update_state("completed") - - return { - "review_recommendations": getattr(self, 'review_recommendations', []), - "knowledge_gaps": [ - { - 'topic_id': gap.topic_id, - 'level': gap.knowledge_level, - 'confidence': gap.confidence - } - for gap in getattr(self, 'knowledge_gaps', []) - ], - "predicted_growth": getattr(self, 'predicted_next_level', None), - "updated_states": updated_states, - "agent": self.name, - "timestamp": datetime.utcnow().isoformat() - } - - def update_knowledge_from_quiz(self, topic_id, is_correct, difficulty): - """ - Autonomous knowledge update based on quiz performance - """ - self.update_state("updating") - self.log(f"Updating knowledge for topic {topic_id}, correct={is_correct}") - - # Use existing tracker but with agent logging - state = self.tracker.update_knowledge( - self.user_id, - topic_id, - is_correct, - difficulty - ) - - self.updates_performed += 1 - self.log(f"Knowledge updated: {state.knowledge_level:.2f}, " - f"confidence: {state.confidence:.2f}") - - return { - "new_level": state.knowledge_level, - "confidence": state.confidence, - "practice_count": state.practice_count, - "agent": self.name - } - - def get_statistics(self): - """Return agent statistics""" - return { - "agent": self.name, - "predictions_made": self.predictions_made, - "updates_performed": self.updates_performed, - "state": self.state, - "memory_size": len(self.memory) - } \ No newline at end of file +def make_nodes(ctx): + @tracked('knowledge') + def profile_learner(state): + profile = ctx.knowledge.profile(state['user_id']) + return {'profile': profile} + + return {'profile_learner': profile_learner} diff --git a/backend/agents/metrics.py b/backend/agents/metrics.py new file mode 100644 index 0000000000000000000000000000000000000000..ecf791b740a76e7562707798a7c980d5b00b5040 --- /dev/null +++ b/backend/agents/metrics.py @@ -0,0 +1,71 @@ +"""Thread-safe per-agent telemetry shown on the dashboard's agent panel.""" +import functools +import threading +import time +from collections import deque +from datetime import datetime + +AGENTS = ('coordinator', 'knowledge', 'teaching', 'assessment', 'tutor', 'recommendation') + + +class AgentMetrics: + def __init__(self): + self._lock = threading.Lock() + self._data = {a: {'runs': 0, 'errors': 0, 'total_ms': 0, 'state': 'idle', 'last_run_at': None} + for a in AGENTS} + self._log = deque(maxlen=200) + + def start(self, agent): + with self._lock: + self._data[agent]['state'] = 'acting' + + def finish(self, agent, ms, ok=True, note=None): + with self._lock: + d = self._data[agent] + d['runs'] += 1 + d['total_ms'] += ms + d['errors'] += 0 if ok else 1 + d['state'] = 'completed' if ok else 'error' + d['last_run_at'] = datetime.utcnow().isoformat(timespec='seconds') + self._log.append({'agent': agent, 'ms': ms, 'ok': ok, 'note': note, 'at': d['last_run_at']}) + + def snapshot(self): + with self._lock: + agents = {} + for name, d in self._data.items(): + agents[name] = { + 'agent': name, + 'state': d['state'] if d['runs'] else 'idle', + 'runs': d['runs'], + 'errors': d['errors'], + 'avg_latency_ms': round(d['total_ms'] / d['runs']) if d['runs'] else 0, + 'last_run_at': d['last_run_at'], + 'memory_size': sum(1 for e in self._log if e['agent'] == name), + } + return agents, list(self._log)[-20:] + + +METRICS = AgentMetrics() + + +def tracked(agent, trace=True): + """Decorator for LangGraph node functions: records latency/errors and (optionally) appends to state.trace.""" + def deco(fn): + @functools.wraps(fn) + def wrapper(state, *args, **kwargs): + METRICS.start(agent) + t0 = time.perf_counter() + try: + update = fn(state, *args, **kwargs) or {} + except Exception: + METRICS.finish(agent, int((time.perf_counter() - t0) * 1000), ok=False) + raise + ms = int((time.perf_counter() - t0) * 1000) + METRICS.finish(agent, ms, note=fn.__name__) + if not trace: + return update + update.setdefault('trace', []) + update['trace'] = list(update['trace']) + [{'agent': agent, 'step': fn.__name__, 'ms': ms}] + return update + return wrapper + return deco diff --git a/backend/agents/recommendation_agent.py b/backend/agents/recommendation_agent.py index fe0dc8d799ce69eee3601075014dfe750454697b..0e1394da609eb1c9a0f48c778236679a5a251747 100644 --- a/backend/agents/recommendation_agent.py +++ b/backend/agents/recommendation_agent.py @@ -1,272 +1,97 @@ """ -Recommendation Agent - Autonomous learning path optimization +RecommendationAgent: ranks what to study next from the learner model. + +score = readiness gate (prerequisite mastery) -> don't recommend what can't be learned yet + + learning potential (1 - effective mastery) + + "zone of proximal development" bonus (predicted success 50-85%) + + spaced-repetition urgency (recall below threshold) + + momentum (already in progress) + goal match + curriculum order tie-break """ -import json -from .base_agent import BaseAgent -from llm_service import LLMService -from agent_knowledge.rules.recommendation_rules import RecommendationRuleEngine -from agent_communication.message_bus import AgentMessageBus -from models import Topic, KnowledgeState -from datetime import datetime +from models import Topic -class RecommendationAgent(BaseAgent): - """ - Autonomous agent responsible for: - - Suggesting next topics - - Optimizing learning paths - - Balancing difficulty - - Considering prerequisites - """ - - def __init__(self): - super().__init__("RA-001", "RecommendationAgent") - self.llm_service = LLMService() - self.rule_engine = RecommendationRuleEngine() - self.message_bus = AgentMessageBus() - - def perceive(self, student_state): - self.update_state("perceiving") - self.user_id = getattr(student_state, 'user_id', None) - self.current_topic_id = getattr(student_state, 'current_topic_id', None) - self.goals = getattr(student_state, 'goals', []) - - # Get all topics and knowledge states - self.all_topics = Topic.query.all() - if self.user_id: - self.knowledge_states = { - ks.topic_id: ks.knowledge_level - for ks in KnowledgeState.query.filter_by(user_id=self.user_id).all() - } - else: - self.knowledge_states = {} - - self.log(f"Analyzing {len(self.all_topics)} topics, " - f"{len(self.knowledge_states)} known states") - - return self - - def decide(self): - """ - Autonomous decisions: - - What topic to recommend next? - - Short-term vs long-term path? - - Review vs new content? - """ - self.update_state("deciding") - - # Decision 1: Calculate scores for all topics - topic_scores = [] - - for topic in self.all_topics: - if topic.id == self.current_topic_id: - continue # Skip current topic - - score = self._calculate_topic_score(topic) - topic_scores.append((topic, score)) - - # Sort by score - topic_scores.sort(key=lambda x: x[1], reverse=True) - - # Decision 2: Choose recommendation strategy - if len(self.knowledge_states) < 3: - # New learner - suggest foundation topics - self.strategy = "foundation_building" - self.recommendations = [t for t, s in topic_scores - if t.difficulty == 'beginner'][:3] - else: - # Experienced learner - balanced approach - self.strategy = "balanced_growth" - self.recommendations = [t for t, s in topic_scores[:5]] - - self.log(f"Strategy: {self.strategy}, {len(self.recommendations)} recommendations") - - return self - - def _calculate_topic_score(self, topic): - """ - Autonomous scoring algorithm for topic recommendation - """ - score = 0 - knowledge_level = self.knowledge_states.get(topic.id, 0) - - # Factor 1: Unstarted topics (high priority for beginners) - if knowledge_level == 0: - score += 5 - # Factor 2: In-progress topics - elif 0 < knowledge_level < 0.7: - score += 3 - # Factor 3: Mastered topics (low priority) - elif knowledge_level >= 0.8: - score += 0.5 - - # Factor 4: Prerequisites - if topic.prerequisites: - prereq_ids = [int(x.strip()) for x in topic.prerequisites.split(',') if x.strip()] - prereqs_met = all( - self.knowledge_states.get(pid, 0) > 0.6 - for pid in prereq_ids - ) - - if prereqs_met: - score += 3 # Ready to learn - else: - score -= 2 # Not ready yet +from .metrics import tracked + + +def score_topics(profile, topics, goals=(), exclude_id=None): + ranked = [] + for t in topics: + if t.id == exclude_id: + continue + p = profile['topics'][t.id] + eff, ready = p['effective_mastery'], p['readiness'] + pred = p['predicted_success'].get('intermediate', 0.5) + mastered = eff >= 0.85 and not p['due_for_review'] + score = 0.0 + score += 3.0 * ready - (3.0 if ready < 1.0 else 0.0) + score += 2.0 * (1 - eff) + score += 1.0 if 0.5 <= pred <= 0.85 else 0.0 + if p['due_for_review']: + score += 2.5 * (1 - p['recall']) + if 0 < p['practice_count'] and eff < 0.85: + score += 1.0 + if any(g.lower() in (t.name + ' ' + t.category).lower() for g in goals if g): + score += 2.0 + score -= 0.04 * (t.position or 0) + if mastered: + score -= 4.0 + + if p['due_for_review']: + reason = f"Review due: estimated recall has dropped to {p['recall']:.0%}" + elif ready < 1.0: + reason = 'Build prerequisites first' + elif p['practice_count'] == 0: + reason = 'You are ready for this new topic' + elif eff < 0.5: + reason = 'Continue building on your progress' + elif eff < 0.85: + reason = 'Almost there, finish mastering this' else: - score += 2 # No prerequisites - easier to start - - # Factor 5: Difficulty match - avg_knowledge = sum(self.knowledge_states.values()) / len(self.knowledge_states) if self.knowledge_states else 0 - - if topic.difficulty == 'beginner' and avg_knowledge < 0.3: - score += 2 - elif topic.difficulty == 'intermediate' and 0.3 <= avg_knowledge < 0.7: - score += 2 - elif topic.difficulty == 'advanced' and avg_knowledge >= 0.7: - score += 2 - - # Factor 6: Goals alignment - if self.goals: - for goal in self.goals: - if goal.lower() in topic.name.lower() or goal.lower() in topic.category.lower(): - score += 4 - - return score - - def act(self): - """ - Execute: Provide recommendations - """ - self.update_state("acting") - self.log("Generating personalized recommendations...") - - if not self.recommendations: - self.log("No suitable recommendations found", "warning") - self.update_state("completed") - return { - "recommendations": [], - "message": "Great progress! Review previous topics or explore new categories.", - "agent": self.name - } - - # Build detailed recommendations - detailed_recommendations = [] - - for topic in self.recommendations: - knowledge_level = self.knowledge_states.get(topic.id, 0) - - # Generate reason for recommendation - if knowledge_level == 0: - reason = "Ready to explore this new topic" - elif knowledge_level < 0.5: - reason = "Continue building on your progress" - elif knowledge_level < 0.8: - reason = "Almost there! Finish mastering this" - else: - reason = "Review to maintain mastery" - - detailed_recommendations.append({ - 'topic_id': topic.id, - 'name': topic.name, - 'category': topic.category, - 'difficulty': topic.difficulty, - 'current_knowledge': knowledge_level, - 'reason': reason, - 'priority': 'high' if knowledge_level == 0 or 0.3 < knowledge_level < 0.7 else 'medium' - }) - - self.recommendations_made += 1 - self.log(f"Recommendations generated (Total: {self.recommendations_made})") - - # Store in memory - self.memory.append({ - "action": "recommendations_generated", - "count": len(detailed_recommendations), - "strategy": self.strategy, - "user_id": self.user_id + reason = 'Mastered: optional refresher' + ranked.append({ + 'topic_id': t.id, 'name': t.name, 'category': t.category, 'difficulty': t.difficulty, + 'description': t.description, 'current_knowledge': round(eff, 3), 'readiness': ready, + 'predicted_success': round(pred, 3), 'score': round(score, 3), 'reason': reason, + 'priority': 'high' if score >= 4 else ('medium' if score >= 2 else 'low'), }) - - self.update_state("completed") - - return { - "recommendations": detailed_recommendations, - "strategy": self.strategy, - "next_best": detailed_recommendations[0] if detailed_recommendations else None, - "agent": self.name, - "timestamp": datetime.utcnow().isoformat() - } - - def create_learning_path(self, target_topic_id): - """ - Autonomous creation of optimal learning path to target topic - """ - self.update_state("planning") - self.log(f"Creating learning path to topic {target_topic_id}") - - target_topic = Topic.query.get(target_topic_id) - - if not target_topic: - return {"error": "Topic not found"} - - path = [] - queue = [target_topic] - visited = set() - - while queue: - topic = queue.pop(0) - - if topic.id in visited: - continue - - visited.add(topic.id) - knowledge_level = self.knowledge_states.get(topic.id, 0) - - # Add to path if not mastered - if knowledge_level < 0.8: - path.insert(0, { - 'topic_id': topic.id, - 'name': topic.name, - 'current_knowledge': knowledge_level, - 'estimated_hours': self._estimate_learning_time(topic, knowledge_level) - }) - - # Add prerequisites to queue - if topic.prerequisites: - prereq_ids = [int(x.strip()) for x in topic.prerequisites.split(',') if x.strip()] - for pid in prereq_ids: - prereq_topic = Topic.query.get(pid) - if prereq_topic and prereq_topic.id not in visited: - queue.append(prereq_topic) - - self.learning_paths_created += 1 - self.log(f"Learning path created with {len(path)} steps") - - return { - "path": path, - "total_topics": len(path), - "estimated_total_hours": sum(t['estimated_hours'] for t in path), - "agent": self.name - } - - def _estimate_learning_time(self, topic, current_knowledge): - """Estimate hours needed based on difficulty and current knowledge""" - base_hours = { - 'beginner': 3, - 'intermediate': 5, - 'advanced': 8 - } - - hours = base_hours.get(topic.difficulty, 5) - remaining = 1 - current_knowledge - - return round(hours * remaining, 1) - - def get_statistics(self): - """Return agent statistics""" - return { - "agent": self.name, - "recommendations_made": self.recommendations_made, - "learning_paths_created": self.learning_paths_created, - "current_strategy": self.strategy if hasattr(self, 'strategy') else None, - "state": self.state, - "memory_size": len(self.memory) - } \ No newline at end of file + ranked.sort(key=lambda r: r['score'], reverse=True) + return ranked + + +def learning_path(profile, topics, target_id, threshold=0.6): + """Prerequisite-ordered path (DFS topological order) of unmastered topics leading to target.""" + by_id = {t.id: t for t in topics} + path, seen = [], set() + + def visit(tid): + if tid in seen or tid not in by_id: + return + seen.add(tid) + for p in by_id[tid].prerequisite_ids: + visit(p) + eff = profile['topics'][tid]['effective_mastery'] + if eff < threshold or tid == target_id: + t = by_id[tid] + hours = {'beginner': 3, 'intermediate': 5, 'advanced': 8}.get(t.difficulty, 5) * (1 - eff) + path.append({'topic_id': tid, 'name': t.name, 'difficulty': t.difficulty, + 'current_knowledge': round(eff, 3), 'estimated_hours': round(hours, 1)}) + + visit(target_id) + return {'target_topic_id': target_id, 'path': path, 'total_topics': len(path), + 'estimated_total_hours': round(sum(p['estimated_hours'] for p in path), 1)} + + +def make_nodes(ctx): + @tracked('recommendation') + def recommend(state): + req = state.get('request', {}) + topics = Topic.query.order_by(Topic.position, Topic.id).all() + ranked = score_topics(state['profile'], topics, goals=req.get('goals') or [], + exclude_id=req.get('current_topic_id')) + strategy = 'foundation_building' if state['profile']['topics_started'] < 3 else 'balanced_growth' + update = {'recommendations': {'recommendations': ranked[:5], 'next_best': ranked[0] if ranked else None, + 'strategy': strategy, 'agent': 'RecommendationAgent'}} + if state.get('task') == 'full_learning_session' and not state.get('topic_id') and ranked: + update['topic_id'] = ranked[0]['topic_id'] + return update + + return {'recommend': recommend} diff --git a/backend/agents/schemas.py b/backend/agents/schemas.py new file mode 100644 index 0000000000000000000000000000000000000000..974c993aaa30889b832fb96c6edbdb113328e6d7 --- /dev/null +++ b/backend/agents/schemas.py @@ -0,0 +1,61 @@ +"""Pydantic schemas used for LLM structured outputs (LangChain `with_structured_output`).""" +from typing import List, Literal + +from pydantic import BaseModel, Field + +Difficulty = Literal['beginner', 'intermediate', 'advanced'] + + +class LessonSection(BaseModel): + title: str = Field(description='Section heading') + body_markdown: str = Field(description='Section content in Markdown. Use ```python fences for code.') + + +class CodeExample(BaseModel): + title: str + code: str = Field(description='Runnable code, no Markdown fences') + language: str = Field(default='python') + explanation: str + + +class PracticeChallenge(BaseModel): + prompt: str = Field(description='A single, self-contained exercise') + starter_code: str = Field(description='Starter code with TODOs; must run in plain Python with no imports beyond the standard library') + expected_output: str + hints: List[str] = Field(description='Three progressively more revealing hints') + + +class Lesson(BaseModel): + title: str + summary: str = Field(description='Two-sentence overview') + objectives: List[str] = Field(description='3-4 measurable learning objectives') + sections: List[LessonSection] + code_examples: List[CodeExample] + key_takeaways: List[str] + practice: PracticeChallenge + estimated_minutes: int = Field(ge=3, le=60) + + +class QuizOptions(BaseModel): + A: str + B: str + C: str + D: str + + +class QuizQuestion(BaseModel): + question: str + options: QuizOptions + correct_answer: Literal['A', 'B', 'C', 'D'] + explanation: str = Field(description='Why the answer is correct and why the main distractor is wrong (2-3 sentences)') + difficulty: Difficulty + concept: str = Field(description='The key concept this question assesses') + + +class Quiz(BaseModel): + questions: List[QuizQuestion] + + +class Hint(BaseModel): + hint: str = Field(description='The hint (2-4 sentences, no full solution unless the level is detailed)') + guiding_question: str = Field(default='', description='Optional question that nudges the learner') diff --git a/backend/agents/state.py b/backend/agents/state.py new file mode 100644 index 0000000000000000000000000000000000000000..f71962288e5b1504524f966f5da167af9c30c168 --- /dev/null +++ b/backend/agents/state.py @@ -0,0 +1,34 @@ +"""Shared LangGraph state and the dependency container passed to every agent node.""" +import operator +from dataclasses import dataclass, field +from typing import Annotated, Any, Optional, TypedDict + + +class LearningState(TypedDict, total=False): + # inputs + task: str # generate_lesson | generate_quiz | provide_hint | recommend_topic | full_learning_session + user_id: int + topic_id: Optional[int] + request: dict # task-specific inputs (question, code, attempt_count, fresh, goals ...) + # written by agents + profile: dict # KnowledgeAgent: learner model + strategy: dict # TeachingAgent (decide): chosen strategy + bandit context + lesson: dict # TeachingAgent (act) + quiz_plan: dict # AssessmentAgent (decide) + quiz: dict # AssessmentAgent (act) + generation_rounds: int # AssessmentAgent generate/validate loop counter + hint: dict # TutorAgent + recommendations: dict # RecommendationAgent + trace: Annotated[list, operator.add] + errors: Annotated[list, operator.add] + + +@dataclass +class AgentContext: + llm: Any # services.llm.LLMService + knowledge: Any # services.knowledge.KnowledgeService + bandit: Any # ml.bandit.StrategyBandit + teaching_rules: Any + tutor_rules: Any + question_templates: list = field(default_factory=list) + config: Any = None diff --git a/backend/agents/teaching_agent.py b/backend/agents/teaching_agent.py index 5b6ab9e9b271b6694651b9a9df9e85e16518c244..931e26d88c1771433286483dffcf983d81919817 100644 --- a/backend/agents/teaching_agent.py +++ b/backend/agents/teaching_agent.py @@ -1,147 +1,114 @@ """ -Teaching Agent - Autonomous content generation and delivery +TeachingAgent + decide: pick a pedagogical strategy = expert rules (prior) + Thompson-sampling bandit (learned) + act: produce a structured lesson (LLM structured output), reusing cached variants to save calls """ -import json -from .base_agent import BaseAgent -from llm_service import LLMService -from agent_knowledge.rules.teaching_rules import TeachingRuleEngine -from agent_communication.message_bus import AgentMessageBus -from agent_communication.protocols import MessageProtocols -from datetime import datetime import random +from langchain_core.messages import HumanMessage, SystemMessage -class TeachingAgent(BaseAgent): - """ - Autonomous agent responsible for: - - Generating personalized lessons - - Adapting teaching style - - Selecting examples based on student performance - """ - - def __init__(self): - super().__init__("TA-001", "TeachingAgent") - self.llm_service = LLMService() - self.rule_engine = TeachingRuleEngine() - self.message_bus = AgentMessageBus() - self.lessons_generated = 0 - self.knowledge_level = 0.0 - self.learning_style = "visual" - self.lesson_complexity = "beginner" - self.current_strategy = {} - - def perceive(self, student_state): - self.update_state("perceiving") - self.log(f"Perceiving student state for user {student_state.user_id}") - - # Update internal state based on student data - self.user_id = student_state.user_id - self.knowledge_level = student_state.knowledge_level - self.learning_style = student_state.learning_style or "visual" - - # Determine lesson complexity based on knowledge level - if self.knowledge_level < 0.3: - self.lesson_complexity = "beginner" - elif self.knowledge_level < 0.7: - self.lesson_complexity = "intermediate" - else: - self.lesson_complexity = "advanced" - - self.update_state("perceived") - return self.state - - def decide(self): - self.update_state("deciding") - - # Use rule engine to determine strategy - student_profile = { - "knowledge_level": self.knowledge_level, - "learning_style": self.learning_style, - # Mock recent performance for now, ideally comes from KnowledgeAgent - "recent_performance": 0.8 - } - - self.current_strategy = self.rule_engine.select_teaching_strategy(student_profile) - self.log(f"Selected teaching strategy: {self.current_strategy['name']}") - - self.update_state("decided") - return self - - def act(self, topic, prompt=None): - self.update_state("acting") - self.log(f"Generating lesson for topic: {topic.name} with strategy {self.current_strategy['name']}") - - # 1. Request updated profile from KnowledgeAgent (Async/Simulated) - self.message_bus.send_message( - self.name, - "KnowledgeAgent", - MessageProtocols.KNOWLEDGE_REQUEST, - MessageProtocols.request_student_profile(self.user_id, topic.id) - ) +from models import Topic, db +from services import content +from services.sandbox import ALLOWED_IMPORTS - try: - # 2. Generate Lesson Structure using Rule Engine (No LLM) - lesson_structure = self.rule_engine.generate_lesson_structure(topic, self.current_strategy) - - # 3. Fill in content (Hybrid: Try Templates first, else Fallback to LLM for specific sections) - # For this MVP, we will use the structure to guide the LLM, reducing its "thinking" time - # In a full impl, we would pull pre-written content from ContentLibrary - - structured_prompt = f""" - Create a lesson for topic '{topic.name}' ({topic.difficulty}) following this structure: - - Strategy: {self.current_strategy['name']} ({self.current_strategy['description']}) - - Sections: - """ - - for section in lesson_structure['sections']: - structured_prompt += f"\n- {section['title']}: {section['instruction_for_llm']}" - - # Fallback to LLM for content generation but with strict structure - lesson_content = self.llm_service.generate_lesson_with_prompt( - topic.name, - topic.difficulty, - self.knowledge_level, - custom_prompt=structured_prompt - ) - - self.lessons_generated += 1 - self.log(f"Lesson generated successfully using rule-guided structure. (Total: {self.lessons_generated})") - - # Store in agent memory - self.memory.append({ - "action": "lesson_generated", - "topic": topic.name, - "strategy": self.current_strategy['name'], - "complexity": self.lesson_complexity, - "user_id": self.user_id - }) - - self.update_state("completed") - - return { - "content": lesson_content, - "metadata": { - "teaching_style": self.current_strategy.get('name', 'default'), - "complexity": self.lesson_complexity, - "example_count": self.current_strategy.get('example_count', 3), - "agent": self.name, - "generated_at": datetime.utcnow().isoformat() - } - } - - except Exception as e: - self.log(f"Error generating lesson: {str(e)}", "error") - self.update_state("error") - return {"error": str(e)} - - def get_statistics(self): - """Return agent statistics""" - return { - "agent": self.name, - "lessons_generated": self.lessons_generated, - "current_style": self.current_style, - "state": self.state, - "memory_size": len(self.memory) - } \ No newline at end of file +from .metrics import tracked +from .schemas import Lesson + +SYSTEM = ( + 'You are an expert instructor who writes concise, accurate, engaging lessons for an adaptive ' + 'e-learning platform. Adapt depth and pacing to the learner profile you are given. ' + 'Use Markdown inside section bodies. Code must be correct and runnable.' +) + + +def complexity_for(knowledge): + if knowledge < 0.3: + return 'beginner' + if knowledge < 0.7: + return 'intermediate' + return 'advanced' + + +def make_nodes(ctx): + @tracked('teaching') + def select_strategy(state): + topic_id = state['topic_id'] + tp = state['profile']['topics'].get(topic_id, {}) + knowledge = tp.get('effective_mastery', 0.0) + style = state.get('request', {}).get('learning_style', 'mixed') + accuracy = tp.get('accuracy') + rule = ctx.teaching_rules.select_teaching_strategy({ + 'knowledge_level': knowledge, + 'learning_style': style, + 'recent_performance': accuracy if accuracy is not None else 1.0, + }) or ctx.teaching_rules.strategies[0] + name, bucket, samples = ctx.bandit.select(knowledge, rule_choice=rule['name']) + chosen = ctx.teaching_rules._find_strategy(name) or rule + return {'strategy': { + 'name': name, + 'description': chosen.get('description', ''), + 'lesson_structure': chosen.get('lesson_structure', {}), + 'rule_choice': rule['name'], + 'bucket': bucket, + 'bandit_samples': {k: round(v, 3) for k, v in samples.items()}, + 'complexity': complexity_for(knowledge), + 'knowledge_level': knowledge, + }} + + def _prompt(topic, strategy, profile, request): + tp = profile['topics'].get(topic.id, {}) + weak_prereqs = [profile['topics'][p]['name'] for p in topic.prerequisite_ids + if p in profile['topics'] and profile['topics'][p]['effective_mastery'] < 0.5] + structure = ctx.teaching_rules.generate_lesson_structure(topic, {'name': strategy['name'], + 'lesson_structure': strategy['lesson_structure']}) + plan = '\n'.join(f"- {s['title']}: {s['instruction_for_llm'].replace('_', ' ')}" for s in structure['sections']) + goals = ', '.join(request.get('goals') or []) or 'not specified' + return [ + SystemMessage(SYSTEM), + HumanMessage( + f"Write a lesson on **{topic.name}** ({topic.category}).\n" + f"Topic description: {topic.description}\n" + f"Key concepts to cover: {', '.join(topic.key_concepts or [])}\n\n" + f"Learner profile:\n" + f"- current mastery: {tp.get('effective_mastery', 0):.0%} (target level: {strategy['complexity']})\n" + f"- predicted success on intermediate questions: {tp.get('predicted_success', {}).get('intermediate', 0.5):.0%}\n" + f"- learning style: {request.get('learning_style', 'mixed')}; goals: {goals}\n" + f"- prerequisites still weak: {', '.join(weak_prereqs) or 'none'} (briefly recap these first if any)\n\n" + f"Pedagogical strategy: {strategy['name']} - {strategy['description']}\n" + f"Follow this section plan:\n{plan}\n\n" + f"Requirements: 3-6 sections; 1-3 code examples; 3-5 key takeaways; one practice challenge whose " + f"starter code runs in plain Python and only imports from: {', '.join(sorted(ALLOWED_IMPORTS))}. " + f"If the topic is not Python-specific, make the challenge a Python simulation of the idea. " + f"Target length ~{structure['metadata']['estimated_time'].split()[0]} minutes of reading." + ), + ] + + @tracked('teaching') + def teach(state): + topic = db.session.get(Topic, state['topic_id']) + strategy = state['strategy'] + request = state.get('request', {}) + key = content.lesson_cache_key(topic.id, strategy['complexity'], strategy['name']) + cached = content.cached_lessons(key) + limit = ctx.config.LESSON_CACHE_VARIANTS + + if cached and (len(cached) >= limit or not ctx.llm.available) and not request.get('fresh'): + row = random.choice(cached) + row.usage_count = (row.usage_count or 0) + 1 + return {'lesson': {'lesson': row.meta_data, 'markdown': row.content, 'source': 'cache'}} + + result = ctx.llm.structured(Lesson, _prompt(topic, strategy, state['profile'], request)) + if result is not None: + lesson = result.model_dump() + md = content.lesson_to_markdown(lesson) + content.store_lesson(key, topic.id, strategy['complexity'], lesson, md) + return {'lesson': {'lesson': lesson, 'markdown': md, 'source': 'llm'}} + + if cached: + row = random.choice(cached) + return {'lesson': {'lesson': row.meta_data, 'markdown': row.content, 'source': 'cache'}} + lesson = content.offline_lesson(topic, strategy['complexity'], strategy['name']) + return {'lesson': {'lesson': lesson, 'markdown': content.lesson_to_markdown(lesson), 'source': 'offline'}, + 'errors': ['llm_unavailable'] if ctx.llm.available else []} + + return {'select_strategy': select_strategy, 'teach': teach} diff --git a/backend/agents/tutor_agent.py b/backend/agents/tutor_agent.py index f00e895e86d4d40cbfb550ff94e11b3401b530f4..c2a5ffa97a0b5b89f8d5f13e3280682881942415 100644 --- a/backend/agents/tutor_agent.py +++ b/backend/agents/tutor_agent.py @@ -1,126 +1,60 @@ """ -Tutor Agent - Autonomous assistance and motivation +TutorAgent + provide_hint: hint ladder (socratic -> conceptual -> direct) chosen by expert rules from the + attempt count, phrased by the LLM with the learner's code, output and mastery as context. """ -import json -from .base_agent import BaseAgent -from llm_service import LLMService -from agent_knowledge.rules.tutor_rules import TutorRuleEngine -from datetime import datetime +from langchain_core.messages import HumanMessage, SystemMessage -class TutorAgent(BaseAgent): - """ - Autonomous agent responsible for: - - Providing hints - - Answering questions - - Motivational support - - Adaptive guidance - """ - - def __init__(self): - super().__init__("TUA-001", "TutorAgent") - self.llm_service = LLMService() - self.rule_engine = TutorRuleEngine() - self.hints_provided = 0 - self.questions_answered = 0 - self.motivation_level = "neutral" - self.strategy = None # To store the selected strategy - - def perceive(self, student_state, context=None): - """ - Perceive student's help needs - - Args: - student_state: object with student's current state (e.g., frustration_level) - context: dict with additional context (e.g., 'attempts') - """ - self.update_state("perceiving") - self.log(f"Perceiving student state. Frustration: {getattr(student_state, 'frustration_level', 'N/A')}") - - # Context might contain recent quiz attempts, time taken, etc. - self.frustration_level = getattr(student_state, 'frustration_level', 'low') - # Simulate attempts count or get from context - self.attempts = context.get('attempts', 1) if context else 1 - - return self - - def decide(self): - """ - Autonomous decisions: - - How much help to provide? - - What teaching approach? - - Level of motivation needed? - """ - self.update_state("deciding") - - # Determine hint strategy - self.strategy = self.rule_engine.select_hint_strategy( - self.attempts, self.frustration_level - ) - - self.log(f"Decided strategy: {self.strategy['name'] if self.strategy else 'default'}") - - return self - - def act(self, prompt=None): - """ - Execute: Provide intelligent hint or answer based on the decided strategy - """ - self.update_state("acting") - self.log(f"Providing help with strategy: {self.strategy['name'] if self.strategy else 'default'}") - - try: - - self.update_state("completed") - - return { - "hint": response, - "hint_level": self.hint_level, - "motivation": self.motivation_level, - "agent": self.name, - "timestamp": datetime.utcnow().isoformat() - } - - except Exception as e: - self.log(f"Error generating hint: {str(e)}", "error") - self.update_state("error") - return { - "hint": "Think about what you've learned. Break the problem into smaller steps!", - "agent": self.name - } - - def provide_motivation(self, user_performance): - """ - Autonomous motivational message based on performance - """ - self.update_state("motivating") - - score = user_performance.get('score', 0) - improvement = user_performance.get('improvement', 0) - - if score >= 0.8: - message = "🌟 Excellent work! You're mastering this topic. Ready for a challenge?" - elif score >= 0.6: - message = "πŸ‘ Good progress! Keep practicing and you'll get there." - elif improvement > 0.1: - message = "πŸ“ˆ Great improvement! Your hard work is paying off." +from models import Topic, db + +from .metrics import tracked +from .schemas import Hint + +LEVEL_INSTRUCTIONS = { + 'subtle': 'Do NOT give the solution. Ask one guiding question and point at where to look.', + 'moderate': 'Explain the underlying concept and outline the approach, but do not write the full solution.', + 'detailed': 'Point out the specific mistake and show the minimal fix with a short code fragment.', +} + + +def make_nodes(ctx): + @tracked('tutor') + def provide_hint(state): + req = state.get('request', {}) + attempts = max(1, int(req.get('attempt_count') or 1)) + strategy = ctx.tutor_rules.select_hint_strategy(attempts, req.get('frustration_level', 'normal')) or {} + level = strategy.get('hint_level', 'moderate') + topic = db.session.get(Topic, state['topic_id']) if state.get('topic_id') else None + tp = state['profile']['topics'].get(state.get('topic_id'), {}) if topic else {} + + messages = [ + SystemMessage('You are a patient, encouraging programming tutor. Keep hints to 2-4 sentences.'), + HumanMessage( + f"Topic: {topic.name if topic else 'general programming'} " + f"(learner mastery {tp.get('effective_mastery', 0):.0%}).\n" + f"Exercise / question: {req.get('question') or 'free practice'}\n" + f"Learner's code:\n```python\n{(req.get('challenge') or '')[:4000]}\n```\n" + f"Last output or error: {(req.get('last_output') or 'n/a')[:1500]}\n" + f"Attempt number: {attempts}. Hint strategy: {strategy.get('name', 'conceptual_reminder')}.\n" + f"{LEVEL_INSTRUCTIONS[level]}" + ), + ] + result = ctx.llm.structured(Hint, messages) + if result is not None: + text = result.hint + (f"\n\n{result.guiding_question}" if result.guiding_question else '') + source = 'llm' else: - message = "πŸ’ͺ Don't give up! Every expert was once a beginner. Take it one step at a time." - - self.log(f"Motivation provided for score {score}") - - return { - "message": message, - "agent": self.name, - "tone": "encouraging" - } - - def get_statistics(self): - """Return agent statistics""" - return { - "agent": self.name, - "hints_provided": self.hints_provided, - "questions_answered": self.questions_answered, - "current_motivation_level": self.motivation_level, - "state": self.state, - "memory_size": len(self.memory) - } \ No newline at end of file + lesson_hints = req.get('practice_hints') or [] + if lesson_hints: + text = lesson_hints[min(attempts, len(lesson_hints)) - 1] + else: + concept = (topic.key_concepts or [topic.name])[0] if topic else 'the core idea' + text = {'subtle': f'What should the program print first? Trace your code line by line and check how it uses {concept}.', + 'moderate': f'Revisit {concept}: write down the steps in plain words, then translate each step into one line of code.', + 'detailed': 'Run a tiny version of the problem, print every intermediate value, and compare it with the expected output to locate the first line that differs.'}[level] + source = 'rules' + return {'hint': {'hint': text, 'hint_level': level, 'strategy': strategy.get('name'), + 'motivation': ctx.tutor_rules.get_motivational_quote(), + 'agent': 'TutorAgent', 'source': source}} + + return {'provide_hint': provide_hint} diff --git a/backend/agents/tutor_chat.py b/backend/agents/tutor_chat.py new file mode 100644 index 0000000000000000000000000000000000000000..8a2820e9841bdc863c01a048a7a392ee9c475717 --- /dev/null +++ b/backend/agents/tutor_chat.py @@ -0,0 +1,101 @@ +""" +Conversational AI tutor with persistent memory. + +A LangGraph MessagesState graph checkpointed to SQLite: one thread per (user, topic), so the +conversation survives restarts and is personalised with the learner model on every turn. +""" +import logging +import os +import sqlite3 + +from langchain_core.messages import AIMessage, HumanMessage, RemoveMessage, SystemMessage +from langgraph.graph import START, MessagesState, StateGraph + +from models import Topic, db + +from .metrics import tracked + +log = logging.getLogger(__name__) +HISTORY_WINDOW = 16 +MAX_STORED_MESSAGES = 60 + + +class TutorChat: + def __init__(self, ctx, db_path): + self.ctx = ctx + os.makedirs(os.path.dirname(db_path) or '.', exist_ok=True) + try: + from langgraph.checkpoint.sqlite import SqliteSaver + self.checkpointer = SqliteSaver(sqlite3.connect(db_path, check_same_thread=False)) + except ImportError: # pragma: no cover + from langgraph.checkpoint.memory import InMemorySaver + log.warning('langgraph-checkpoint-sqlite not installed; tutor memory is in-memory only') + self.checkpointer = InMemorySaver() + self.graph = self._build() + + def _system_prompt(self, user_id, topic_id): + profile = self.ctx.knowledge.profile(user_id) + topic = db.session.get(Topic, topic_id) if topic_id else None + weak = ', '.join(w['name'] for w in profile['weak_topics']) or 'none yet' + due = ', '.join(r['name'] for r in profile['review_queue'][:3]) or 'none' + focus = '' + if topic: + tp = profile['topics'].get(topic.id, {}) + focus = (f"The learner is currently studying '{topic.name}' ({topic.description}); " + f"their mastery is {tp.get('effective_mastery', 0):.0%}. Key concepts: " + f"{', '.join(topic.key_concepts or [])}.\n") + return ( + 'You are an expert, friendly AI tutor on an adaptive learning platform. Teach Socratically: ' + 'check understanding, give small worked examples, and prefer guiding questions over full ' + 'solutions for exercises. Use Markdown and ```python code fences. Keep answers focused ' + '(under ~250 words unless asked for more).\n' + f"{focus}Learner's weak topics: {weak}. Topics due for review: {due}. " + f"Overall average mastery: {profile['average_knowledge']:.0%}." + ) + + def _build(self): + ctx = self.ctx + + @tracked('tutor', trace=False) + def respond(state, config): + cfg = config['configurable'] + history = state['messages'][-HISTORY_WINDOW:] + reply = ctx.llm.chat([SystemMessage(self._system_prompt(cfg['user_id'], cfg.get('topic_id')))] + history) + if reply is None: + topic = db.session.get(Topic, cfg['topic_id']) if cfg.get('topic_id') else None + concepts = ', '.join((topic.key_concepts or [])[:3]) if topic else '' + reply = ('I am running in offline mode right now (no LLM configured), so I cannot answer ' + 'free-form questions. ' + (f'For **{topic.name}**, focus on: {concepts}. ' if topic else '') + + 'Try the lesson, the practice playground and the adaptive quiz meanwhile!') + update = [AIMessage(reply)] + overflow = len(state['messages']) + 1 - MAX_STORED_MESSAGES + if overflow > 0: # keep the checkpoint small + update += [RemoveMessage(id=m.id) for m in state['messages'][:overflow]] + return {'messages': update} + + g = StateGraph(MessagesState) + g.add_node('respond', respond) + g.add_edge(START, 'respond') + return g.compile(checkpointer=self.checkpointer) + + @staticmethod + def _config(user_id, topic_id): + return {'configurable': {'thread_id': f'user-{user_id}:topic-{topic_id or "general"}', + 'user_id': user_id, 'topic_id': topic_id}} + + def send(self, user_id, topic_id, message): + out = self.graph.invoke({'messages': [HumanMessage(message)]}, self._config(user_id, topic_id)) + return out['messages'][-1].content + + def history(self, user_id, topic_id): + snap = self.graph.get_state(self._config(user_id, topic_id)) + msgs = snap.values.get('messages', []) if snap and snap.values else [] + return [{'role': 'user' if isinstance(m, HumanMessage) else 'assistant', 'content': m.content} + for m in msgs if isinstance(m, (HumanMessage, AIMessage))] + + def clear(self, user_id, topic_id): + thread = self._config(user_id, topic_id)['configurable']['thread_id'] + try: + self.checkpointer.delete_thread(thread) + except Exception as exc: # pragma: no cover + log.warning('Could not clear tutor thread %s: %s', thread, exc) diff --git a/backend/app.py b/backend/app.py index 4ab1deb7556cd10415e048bede6e0460d740a9e7..906234e0d1d65082d4782106d5016d2a96487eb3 100644 --- a/backend/app.py +++ b/backend/app.py @@ -1,625 +1,113 @@ -from flask import Flask, request, jsonify, session -from flask_cors import CORS -from models import db, User, Topic, KnowledgeState, LearningSession, QuizAttempt -from knowledge_tracker import KnowledgeTracker -from llm_service import LLMService -from config import Config -from agents.coordinator_agent import CoordinatorAgent +"""Flask application factory. `gunicorn app:app` serves the module-level instance.""" +import json +import logging import os -from datetime import datetime import re +import sqlite3 +from types import SimpleNamespace -app = Flask(__name__) -app.config.from_object(Config) +from flask import Flask, jsonify +from flask_cors import CORS +from sqlalchemy import event +from sqlalchemy.engine import Engine + +from agent_knowledge.rules.teaching_rules import TeachingRuleEngine +from agent_knowledge.rules.tutor_rules import TutorRuleEngine +from agents.graph import Coordinator +from agents.state import AgentContext +from agents.tutor_chat import TutorChat +from config import BASE_DIR, Config +from curriculum.seed import seed_all +from ml.bandit import StrategyBandit +from models import db, migrate_schema +from routes import api +from services.knowledge import KnowledgeService +from services.llm import LLMService + +logging.basicConfig(level=os.environ.get('LOG_LEVEL', 'INFO'), + format='%(asctime)s %(levelname)s %(name)s: %(message)s') +log = logging.getLogger('app') + + +@event.listens_for(Engine, 'connect') +def _sqlite_pragmas(dbapi_conn, _record): + if isinstance(dbapi_conn, sqlite3.Connection): + cur = dbapi_conn.cursor() + cur.execute('PRAGMA journal_mode=WAL') + cur.execute('PRAGMA busy_timeout=5000') + cur.execute('PRAGMA synchronous=NORMAL') + cur.close() + + +def build_services(app): + cfg = SimpleNamespace(**{k: app.config[k] for k in app.config if k.isupper()}) + with open(os.path.join(BASE_DIR, 'agent_knowledge', 'knowledge_bases', 'question_templates.json')) as f: + templates = json.load(f).get('question_templates', []) + teaching_rules = TeachingRuleEngine() + ctx = AgentContext( + llm=LLMService(cfg), + knowledge=KnowledgeService(cfg.ML_ARTIFACTS_DIR), + bandit=StrategyBandit(teaching_rules.strategies), + teaching_rules=teaching_rules, + tutor_rules=TutorRuleEngine(), + question_templates=templates, + config=cfg, + ) + tutor_db = app.config.get('TUTOR_DB_PATH') or os.path.join(cfg.DATA_DIR, 'tutor_memory.db') + return SimpleNamespace(llm=ctx.llm, knowledge=ctx.knowledge, bandit=ctx.bandit, ctx=ctx, + coordinator=Coordinator(ctx), tutor_chat=TutorChat(ctx, tutor_db)) -# UPDATED CORS CONFIGURATION -CORS(app, - supports_credentials=True, - origins=['http://localhost:3000', 'https://adaptive-e-learning-system.vercel.app'], # placeholder - will improve with regex or wildcard - allow_headers=['Content-Type', 'Authorization'], - methods=['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']) -db.init_app(app) +def create_app(config_object=Config): + app = Flask(__name__) + app.config.from_object(config_object) + if app.config['SECRET_KEY'] == 'dev-only-change-me' and not app.config.get('TESTING'): + log.warning('SECRET_KEY is not set: tokens will not survive restarts. Set SECRET_KEY in production.') -# Initialize agents and services + origins = list(app.config['CORS_ORIGINS']) + if app.config.get('CORS_ORIGIN_REGEX'): + origins.append(re.compile(app.config['CORS_ORIGIN_REGEX'])) + CORS(app, supports_credentials=True, origins=origins, + allow_headers=['Content-Type', 'Authorization'], methods=['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']) -knowledge_tracker = KnowledgeTracker() -llm_service = LLMService() -coordinator = CoordinatorAgent() + if app.config['SQLALCHEMY_DATABASE_URI'].startswith('sqlite:///'): + os.makedirs(os.path.dirname(app.config['SQLALCHEMY_DATABASE_URI'][len('sqlite:///'):]), exist_ok=True) + db.init_app(app) -# Initialize database and sample data -def init_db(): with app.app_context(): db.create_all() - - # Create sample topics if none exist - if Topic.query.count() == 0: - sample_topics = [ - Topic(name="Python Basics", category="Programming", difficulty="beginner", - description="Introduction to Python programming"), - Topic(name="Data Structures", category="Programming", difficulty="intermediate", - description="Learn about arrays, lists, stacks, and queues", prerequisites="1"), - Topic(name="Object-Oriented Programming", category="Programming", difficulty="intermediate", - description="Classes, objects, inheritance, and polymorphism", prerequisites="1"), - Topic(name="Algorithms", category="Programming", difficulty="advanced", - description="Sorting, searching, and algorithm complexity", prerequisites="2"), - Topic(name="Machine Learning Basics", category="AI/ML", difficulty="intermediate", - description="Introduction to ML concepts and algorithms", prerequisites="1,2"), - Topic(name="Web Development", category="Web", difficulty="beginner", - description="HTML, CSS, and JavaScript fundamentals"), - Topic(name="Database Design", category="Database", difficulty="intermediate", - description="SQL and database normalization", prerequisites="1"), - Topic(name="Neural Networks", category="AI/ML", difficulty="advanced", - description="Deep learning and neural network architectures", prerequisites="5"), - ] - db.session.bulk_save_objects(sample_topics) - db.session.commit() - -# UPDATED: Root route now returns API info instead of template -@app.route('/') -def index(): - return jsonify({ - 'message': 'Adaptive E-Learning API', - 'version': '1.0.0', - 'status': 'running', - 'ai_agents': '5 autonomous agents active', - 'endpoints': { - 'auth': '/api/login, /api/register, /api/logout, /api/current-user', - 'topics': '/api/topics, /api/topics/', - 'learning': '/api/generate-lesson', - 'quiz': '/api/generate-quiz, /api/submit-answer', - 'progress': '/api/progress-summary, /api/knowledge-state/', - 'utility': '/api/check-code, /api/ask-challenge-hint, /api/agent-status' - } - }) - -# REMOVED: All HTML template routes (dashboard, learn, quiz, progress) -# React frontend handles all routing - -# API Routes -@app.route('/api/register', methods=['POST']) -def register(): - data = request.json - - existing_user = User.query.filter_by(username=data['username']).first() - if existing_user: - return jsonify({'error': 'Username already exists'}), 400 - - user = User( - username=data['username'], - email=data['email'] - ) - db.session.add(user) - db.session.commit() - - session['user_id'] = user.id - session['username'] = user.username - - return jsonify({ - 'message': 'User registered successfully', - 'user_id': user.id, - 'username': user.username - }) - -@app.route('/api/login', methods=['POST']) -def login(): - data = request.json - user = User.query.filter_by(username=data['username']).first() - - if user: - session['user_id'] = user.id - session['username'] = user.username - return jsonify({ - 'message': 'Login successful', - 'user_id': user.id, - 'username': user.username - }) - else: - return jsonify({'error': 'User not found'}), 404 - -@app.route('/api/current-user', methods=['GET']) -def current_user(): - if 'user_id' in session: - return jsonify({ - 'user_id': session['user_id'], - 'username': session['username'] - }) - return jsonify({'error': 'Not logged in'}), 401 - -@app.route('/api/logout', methods=['POST']) -def logout(): - session.clear() - return jsonify({'message': 'Logged out successfully'}) - -@app.route('/api/topics', methods=['GET']) -def get_topics(): - topics = Topic.query.all() - return jsonify([{ - 'id': t.id, - 'name': t.name, - 'category': t.category, - 'difficulty': t.difficulty, - 'description': t.description - } for t in topics]) + migrate_schema() + added = seed_all() + if added: + log.info('Seeded %d questions into the question bank', added) + app.extensions['elearn'] = build_services(app) + log.info('LLM: %s | knowledge model: %s', app.extensions['elearn'].llm.info()['provider'], + 'transformer+bkt' if app.extensions['elearn'].knowledge.kt.available else 'bkt') -@app.route('/api/topics/', methods=['GET']) -def get_topic(topic_id): - topic = Topic.query.get_or_404(topic_id) - return jsonify({ - 'id': topic.id, - 'name': topic.name, - 'category': topic.category, - 'difficulty': topic.difficulty, - 'description': topic.description - }) + app.register_blueprint(api) -def format_lesson_content(content): - """Format lesson content for better display""" - import re - - # Remove multiple consecutive blank lines - content = re.sub(r'\n\s*\n\s*\n+', '\n\n', content) - - # Remove extra whitespace from each line - content = '\n'.join(line.strip() for line in content.split('\n')) - - # Convert markdown code blocks to HTML - content = re.sub(r'```python\n(.*?)\n```', r'
\1
', content, flags=re.DOTALL) - content = re.sub(r'```\n(.*?)\n```', r'
\1
', content, flags=re.DOTALL) - - # Convert markdown headers to HTML - content = re.sub(r'^### (.*?)$', r'

\1

', content, flags=re.MULTILINE) - content = re.sub(r'^## (.*?)$', r'

\1

', content, flags=re.MULTILINE) - content = re.sub(r'^# (.*?)$', r'

\1

', content, flags=re.MULTILINE) - - # Convert markdown bold to HTML - content = re.sub(r'\*\*(.*?)\*\*', r'\1', content) - - # Convert inline code to HTML (before lists to preserve code in lists) - content = re.sub(r'`([^`]+)`', r'\1', content) - - # Convert markdown lists to HTML - IMPROVED - lines = content.split('\n') - in_list = False - result_lines = [] - - for i, line in enumerate(lines): - line = line.strip() - - # Skip empty lines - if not line: - if in_list: - result_lines.append('') - in_list = False - continue - - # Handle list items - if line.startswith('- '): - if not in_list: - result_lines.append('
    ') - in_list = True - result_lines.append(f'
  • {line[2:]}
  • ') - else: - if in_list: - result_lines.append('
') - in_list = False - result_lines.append(line) - - if in_list: - result_lines.append('') - - content = '\n'.join(result_lines) - - # Convert paragraphs - NO NEWLINES - lines = content.split('\n') - formatted_lines = [] - in_pre = False - - for line in lines: - line = line.strip() - - # Skip completely empty lines - if not line: - continue - - # Handle pre blocks - if '
' in line:
-            in_pre = True
-            formatted_lines.append(line)
-            continue
-        elif '
' in line: - in_pre = False - formatted_lines.append(line) - continue - elif in_pre: - formatted_lines.append(line) - continue - - # Keep HTML tags as-is - if line.startswith('') or line.startswith('') or line.startswith('
  • '): - formatted_lines.append(line) - else: - # Wrap non-HTML content in paragraph - formatted_lines.append(f'

    {line}

    ') - - # Join WITHOUT newlines to eliminate all spacing - return ''.join(formatted_lines) - -def format_study_tips(content): - """Format study tips markdown to HTML""" - import re - - # Convert **bold** to HTML - content = re.sub(r'\*\*(.*?)\*\*', r'\1', content) - - # Convert bullet points to HTML list - lines = content.split('\n') - formatted_lines = [] - in_list = False - - for line in lines: - line = line.strip() - if not line: - continue - - # Check if it's a header - if line.endswith(':') and not line.startswith('-') and not line.startswith('β€’'): - if in_list: - formatted_lines.append('') - in_list = False - formatted_lines.append(f'

    {line}

    ') - # Check if it's a bullet point - elif line.startswith('- ') or line.startswith('β€’ '): - if not in_list: - formatted_lines.append('
      ') - in_list = True - # Remove the bullet character - text = line[2:] if line.startswith('- ') else line[2:] - formatted_lines.append(f'
    • {text}
    • ') - else: - if in_list: - formatted_lines.append('
    ') - in_list = False - formatted_lines.append(f'

    {line}

    ') - - if in_list: - formatted_lines.append('') - - return ''.join(formatted_lines) - -@app.route('/api/generate-lesson', methods=['POST']) -def generate_lesson(): - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - data = request.json - topic_id = data['topic_id'] - - # Use Coordinator Agent - result = coordinator.perceive({ - 'task': 'generate_lesson', - 'user_id': session['user_id'], - 'context': { - 'topic_id': topic_id, - 'learning_history': [] - } - }).decide().act() - - if not result['success']: - return jsonify({'error': result.get('error')}), 500 - - # Extract teaching agent result - teaching_result = result['results'].get('TeachingAgent', {}) - - # Format content - content = format_lesson_content(teaching_result.get('content', '')) - - # Save to database - topic = Topic.query.get(topic_id) - - learning_session = LearningSession( - user_id=session['user_id'], - topic_id=topic_id, - content=content, - difficulty=teaching_result.get('metadata', {}).get('complexity', 'beginner') - ) - db.session.add(learning_session) - db.session.commit() - - return jsonify({ - 'content': content, - 'difficulty': teaching_result.get('metadata', {}).get('complexity'), - 'knowledge_level': teaching_result.get('metadata', {}).get('knowledge_level', 0), - 'topic_name': topic.name, - 'agent_metadata': teaching_result.get('metadata', {}) - }) - -@app.route('/api/generate-quiz', methods=['POST']) -def generate_quiz(): - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - data = request.json - topic_id = data['topic_id'] - - # Use Coordinator Agent - result = coordinator.perceive({ - 'task': 'generate_quiz', - 'user_id': session['user_id'], - 'context': { - 'topic_id': topic_id, - 'recent_performance': [] - } - }).decide().act() - - if not result['success']: - return jsonify({'error': result.get('error')}), 500 - - assessment_result = result['results'].get('AssessmentAgent', {}) - - topic = Topic.query.get(topic_id) - - return jsonify({ - 'questions': assessment_result.get('questions', []), - 'difficulty': 'adaptive', - 'topic_name': topic.name, - 'topic_id': topic_id, - 'agent_metadata': assessment_result.get('metadata', {}) - }) - -@app.route('/api/submit-answer', methods=['POST']) -def submit_answer(): - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - data = request.json - topic_id = data['topic_id'] - question = data['question'] - user_answer = data['user_answer'] - correct_answer = data['correct_answer'] - difficulty = data['difficulty'] - - is_correct = user_answer == correct_answer - - # Save quiz attempt - attempt = QuizAttempt( - user_id=session['user_id'], - topic_id=topic_id, - question=question, - user_answer=user_answer, - correct_answer=correct_answer, - is_correct=is_correct, - difficulty=difficulty - ) - db.session.add(attempt) - db.session.commit() - - # Update knowledge state - state = knowledge_tracker.update_knowledge( - session['user_id'], - topic_id, - is_correct, - difficulty - ) - - # Generate explanation - topic = Topic.query.get(topic_id) - explanation = llm_service.explain_answer( - question, - user_answer, - correct_answer, - topic.name - ) - - return jsonify({ - 'is_correct': is_correct, - 'explanation': explanation, - 'new_knowledge_level': state.knowledge_level, - 'confidence': state.confidence - }) - -@app.route('/api/knowledge-state/', methods=['GET']) -def get_knowledge_state(topic_id): - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - state = knowledge_tracker.get_or_create_knowledge_state( - session['user_id'], topic_id - ) - - topic = Topic.query.get(topic_id) - - return jsonify({ - 'topic_id': topic_id, - 'topic_name': topic.name, - 'knowledge_level': state.knowledge_level, - 'confidence': state.confidence, - 'practice_count': state.practice_count, - 'last_practiced': state.last_practiced.isoformat() - }) + @app.errorhandler(404) + def not_found(_e): + return jsonify({'error': 'Not found'}), 404 -@app.route('/api/progress-summary', methods=['GET']) -def get_progress_summary(): - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - summary = knowledge_tracker.get_progress_summary(session['user_id']) - - # Enhance with topic names - for topic_list in ['weak_topics', 'strong_topics']: - for item in summary[topic_list]: - topic = Topic.query.get(item['id']) - if topic: - item['name'] = topic.name - - return jsonify(summary) + @app.errorhandler(405) + def not_allowed(_e): + return jsonify({'error': 'Method not allowed'}), 405 -@app.route('/api/next-topic', methods=['GET']) -def get_next_topic(): - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - current_topic_id = request.args.get('current_topic_id', type=int) - - # Use Coordinator Agent - result = coordinator.perceive({ - 'task': 'recommend_topic', - 'user_id': session['user_id'], - 'context': { - 'current_topic_id': current_topic_id - } - }).decide().act() - - if not result['success']: - return jsonify({'message': 'No recommendations'}), 404 - - recommendation_result = result['results'].get('RecommendationAgent', {}) - next_best = recommendation_result.get('next_best') - - if next_best: - return jsonify({ - 'id': next_best['topic_id'], - 'name': next_best['name'], - 'category': next_best['category'], - 'difficulty': next_best['difficulty'], - 'description': next_best['reason'], - 'agent_recommendation': True - }) - - return jsonify({'message': 'No recommendations available'}), 404 + @app.errorhandler(500) + def server_error(_e): + db.session.rollback() + return jsonify({'error': 'Internal server error'}), 500 -@app.route('/api/study-tips', methods=['GET']) -def get_study_tips(): - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - summary = knowledge_tracker.get_progress_summary(session['user_id']) - - weak_topic_names = [] - strong_topic_names = [] - - for item in summary['weak_topics']: - topic = Topic.query.get(item['id']) - if topic: - weak_topic_names.append(topic.name) - - for item in summary['strong_topics']: - topic = Topic.query.get(item['id']) - if topic: - strong_topic_names.append(topic.name) - - tips = llm_service.generate_study_tips(weak_topic_names, strong_topic_names) - - # Format the tips - formatted_tips = format_study_tips(tips) - - return jsonify({'tips': formatted_tips}) + @app.teardown_request + def _rollback_on_error(exc): + if exc is not None: + db.session.rollback() -@app.route('/api/check-code', methods=['POST']) -def check_code(): - """Execute Python code safely and return output""" - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - data = request.json - user_code = data.get('code', '') - - # Security: limit execution time and dangerous operations - if any(keyword in user_code.lower() for keyword in ['import os', 'import sys', 'eval', 'exec', 'open', 'file', '__import__']): - return jsonify({ - 'success': False, - 'output': 'Error: Restricted operations detected. Please use only basic Python syntax.', - 'error': True - }) - - try: - # Capture output - import io - import sys - from contextlib import redirect_stdout - - output_buffer = io.StringIO() - - with redirect_stdout(output_buffer): - # Create a restricted namespace - namespace = {'__builtins__': { - 'print': print, - 'input': lambda x='': '', - 'len': len, - 'range': range, - 'str': str, - 'int': int, - 'float': float, - 'list': list, - 'dict': dict, - 'set': set, - 'tuple': tuple, - 'sum': sum, - 'max': max, - 'min': min, - 'abs': abs, - 'round': round, - }} - - # Execute code - exec(user_code, namespace) - - output = output_buffer.getvalue() - - return jsonify({ - 'success': True, - 'output': output if output else 'Code executed successfully (no output)', - 'error': False - }) - - except Exception as e: - return jsonify({ - 'success': False, - 'output': f'Error: {str(e)}', - 'error': True - }) + return app -@app.route('/api/ask-challenge-hint', methods=['POST']) -def ask_challenge_hint(): - """Get hint for practice challenge using LLM""" - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - data = request.json - - # Use Coordinator Agent with Tutor Agent - result = coordinator.perceive({ - 'task': 'provide_hint', - 'user_id': session['user_id'], - 'context': { - 'question': data.get('question'), - 'challenge': data.get('challenge'), - 'attempt_count': data.get('attempt_count', 1), - 'frustration_level': 'normal' - } - }).decide().act() - - if not result['success']: - return jsonify({'hint': 'Break the problem into smaller steps!'}), 200 - - tutor_result = result['results'] - - return jsonify({ - 'hint': tutor_result.get('hint'), - 'hint_level': tutor_result.get('hint_level'), - 'agent': tutor_result.get('agent') - }) -@app.route('/api/agent-status', methods=['GET']) -def get_agent_status(): - """Get status of all agents""" - if 'user_id' not in session: - return jsonify({'error': 'Not logged in'}), 401 - - status = coordinator.get_agent_status() - return jsonify(status) +app = create_app() if os.environ.get('ELEARN_NO_AUTOAPP') != '1' else None if __name__ == '__main__': - init_db() - port = int(os.environ.get("PORT", 7860)) - app.run(debug=True, host='0.0.0.0', port=port) \ No newline at end of file + app.run(debug=os.environ.get('FLASK_DEBUG') == '1', host='0.0.0.0', port=int(os.environ.get('PORT', 7860))) diff --git a/backend/config.py b/backend/config.py index 18367817b0c218f083e8050d80f49149a6c0e6ae..ad226298d876f3c2438a87b2fc0282d712fe2b96 100644 --- a/backend/config.py +++ b/backend/config.py @@ -3,19 +3,70 @@ from dotenv import load_dotenv load_dotenv() -class Config: - SECRET_KEY = os.environ.get('SECRET_KEY') or 'akatsuki-bench-Area51' +BASE_DIR = os.path.abspath(os.path.dirname(__file__)) + + +def _default_data_dir(): + """Prefer HF Spaces persistent storage (/data) when it is mounted and writable.""" + if os.path.isdir('/data') and os.access('/data', os.W_OK): + return '/data' + return os.path.join(os.path.dirname(BASE_DIR), 'data') + - basedir = os.path.abspath(os.path.dirname(__file__)) - SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(os.path.dirname(basedir), 'data', 'database.db') +def _bool(name, default=False): + return os.environ.get(name, str(default)).lower() in ('1', 'true', 'yes') + +class Config: + SECRET_KEY = os.environ.get('SECRET_KEY') or 'dev-only-change-me' + + DATA_DIR = os.environ.get('DATA_DIR') or _default_data_dir() + SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or 'sqlite:///' + os.path.join(DATA_DIR, 'database.db') SQLALCHEMY_TRACK_MODIFICATIONS = False - GEMINI_API_KEY = os.environ.get('GEMINI_API_KEY') - - # Knowledge Tracing Parameters - INITIAL_KNOWLEDGE = 0.0 - LEARNING_RATE = 0.15 # Increased slightly for faster progression - FORGETTING_RATE = 0.05 - - # Difficulty Levels - DIFFICULTY_LEVELS = ['beginner', 'intermediate', 'advanced'] \ No newline at end of file + SQLALCHEMY_ENGINE_OPTIONS = {'pool_pre_ping': True} + + # Cross-site cookies (Vercel frontend -> HF backend) need SameSite=None; Secure. + # Bearer tokens are the primary auth mechanism, cookies are a fallback. + SESSION_COOKIE_SAMESITE = os.environ.get('SESSION_COOKIE_SAMESITE', 'None') + SESSION_COOKIE_SECURE = _bool('SESSION_COOKIE_SECURE', True) + TOKEN_MAX_AGE = int(os.environ.get('TOKEN_MAX_AGE', 60 * 60 * 24 * 14)) + + CORS_ORIGINS = [o.strip() for o in os.environ.get( + 'CORS_ORIGINS', + 'http://localhost:3000,http://localhost:5173,https://adaptive-e-learning-system.vercel.app' + ).split(',') if o.strip()] + # Vercel preview deployments + CORS_ORIGIN_REGEX = os.environ.get('CORS_ORIGIN_REGEX', r'https://adaptive-e-learning-system.*\.vercel\.app') + + # LLM + GEMINI_API_KEY = os.environ.get('GEMINI_API_KEY') or os.environ.get('GOOGLE_API_KEY') + LLM_PROVIDER = os.environ.get('LLM_PROVIDER', 'gemini' if GEMINI_API_KEY else 'offline') + LLM_MODEL = os.environ.get('LLM_MODEL', 'gemini-2.5-flash') + LLM_TEMPERATURE = float(os.environ.get('LLM_TEMPERATURE', 0.6)) + LLM_TIMEOUT = int(os.environ.get('LLM_TIMEOUT', 60)) + LLM_MAX_RETRIES = int(os.environ.get('LLM_MAX_RETRIES', 2)) + + # Content reuse: how many cached lesson variants to keep per (topic, level, strategy) + LESSON_CACHE_VARIANTS = int(os.environ.get('LESSON_CACHE_VARIANTS', 3)) + QUIZ_SIZE_MIN = 4 + QUIZ_SIZE_MAX = 6 + + # Knowledge tracing + ML_ARTIFACTS_DIR = os.environ.get('ML_ARTIFACTS_DIR') or os.path.join(BASE_DIR, 'ml', 'artifacts') + TARGET_SUCCESS_RATE = 0.7 # "desirable difficulty" target for adaptive quizzes + MASTERY_THRESHOLD = 0.8 + PREREQ_READY_THRESHOLD = 0.6 + + # Code sandbox + SANDBOX_TIMEOUT_S = 5 + SANDBOX_MEMORY_MB = 256 + SANDBOX_MAX_OUTPUT = 10_000 + + DIFFICULTY_LEVELS = ['beginner', 'intermediate', 'advanced'] + + +class TestConfig(Config): + TESTING = True + SQLALCHEMY_DATABASE_URI = 'sqlite://' + SESSION_COOKIE_SECURE = False + LLM_PROVIDER = 'offline' diff --git a/backend/curriculum/__init__.py b/backend/curriculum/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/backend/curriculum/curriculum.json b/backend/curriculum/curriculum.json new file mode 100644 index 0000000000000000000000000000000000000000..592a94696a944c6b20976e2e7fb4ea906928454c --- /dev/null +++ b/backend/curriculum/curriculum.json @@ -0,0 +1,65 @@ +{ + "version": 2, + "topics": [ + {"slug": "python-basics", "name": "Python Basics", "category": "Programming", "difficulty": "beginner", + "description": "Variables, data types, operators, input/output and the Python REPL.", + "prerequisites": [], "key_concepts": ["variables", "int/float/str/bool", "operators", "print and f-strings", "type conversion"]}, + {"slug": "control-flow", "name": "Control Flow", "category": "Programming", "difficulty": "beginner", + "description": "if/elif/else, for and while loops, break/continue and comprehensions.", + "prerequisites": ["python-basics"], "key_concepts": ["conditionals", "for loops", "while loops", "range()", "list comprehensions"]}, + {"slug": "functions", "name": "Functions", "category": "Programming", "difficulty": "beginner", + "description": "Defining functions, arguments, return values, scope and lambdas.", + "prerequisites": ["control-flow"], "key_concepts": ["def and return", "default and keyword args", "*args/**kwargs", "scope (LEGB)", "lambda"]}, + {"slug": "data-structures", "name": "Data Structures", "category": "Programming", "difficulty": "intermediate", + "description": "Lists, tuples, dicts, sets, stacks and queues and when to use each.", + "prerequisites": ["functions"], "key_concepts": ["lists vs tuples", "dict lookups", "sets", "stack/queue (deque)", "time complexity of operations"]}, + {"slug": "oop", "name": "Object-Oriented Programming", "category": "Programming", "difficulty": "intermediate", + "description": "Classes, objects, inheritance, polymorphism and dunder methods.", + "prerequisites": ["functions"], "key_concepts": ["class and __init__", "instance vs class attributes", "inheritance and super()", "polymorphism", "dunder methods"]}, + {"slug": "error-handling-testing", "name": "Error Handling & Testing", "category": "Programming", "difficulty": "intermediate", + "description": "Exceptions, try/except/finally, custom errors and unit testing with pytest.", + "prerequisites": ["functions"], "key_concepts": ["try/except/else/finally", "raising exceptions", "custom exceptions", "assert", "pytest basics"]}, + {"slug": "algorithms", "name": "Algorithms", "category": "Programming", "difficulty": "advanced", + "description": "Sorting, searching, recursion, Big-O analysis and classic algorithm patterns.", + "prerequisites": ["data-structures"], "key_concepts": ["Big-O notation", "binary search", "merge/quick sort", "recursion", "two pointers and sliding window"]}, + {"slug": "web-fundamentals", "name": "Web Development", "category": "Web", "difficulty": "beginner", + "description": "HTML structure, CSS styling and how browsers render pages.", + "prerequisites": [], "key_concepts": ["HTML elements", "CSS selectors", "box model", "flexbox", "HTTP request/response"]}, + {"slug": "javascript-dom", "name": "JavaScript & the DOM", "category": "Web", "difficulty": "intermediate", + "description": "JavaScript syntax, events, DOM manipulation and async/await.", + "prerequisites": ["web-fundamentals"], "key_concepts": ["let/const", "arrow functions", "DOM querying", "event listeners", "promises and async/await"]}, + {"slug": "rest-apis", "name": "REST APIs", "category": "Web", "difficulty": "intermediate", + "description": "Designing and consuming REST APIs with HTTP verbs, status codes and JSON.", + "prerequisites": ["functions", "web-fundamentals"], "key_concepts": ["HTTP methods", "status codes", "JSON", "statelessness", "authentication tokens"]}, + {"slug": "database-design", "name": "Database Design", "category": "Database", "difficulty": "intermediate", + "description": "Relational modeling, keys, normalization and ER diagrams.", + "prerequisites": ["python-basics"], "key_concepts": ["tables and keys", "one-to-many / many-to-many", "normalization (1NF-3NF)", "indexes", "ER diagrams"]}, + {"slug": "sql-querying", "name": "SQL Querying", "category": "Database", "difficulty": "intermediate", + "description": "SELECT, JOINs, GROUP BY, subqueries and window functions.", + "prerequisites": ["database-design"], "key_concepts": ["SELECT/WHERE", "JOIN types", "GROUP BY/HAVING", "subqueries", "window functions"]}, + {"slug": "statistics", "name": "Statistics for Data Science", "category": "AI/ML", "difficulty": "beginner", + "description": "Descriptive statistics, probability, distributions and hypothesis testing.", + "prerequisites": ["python-basics"], "key_concepts": ["mean/median/variance", "probability rules", "normal distribution", "correlation", "hypothesis tests and p-values"]}, + {"slug": "numpy-pandas", "name": "NumPy & Pandas", "category": "AI/ML", "difficulty": "intermediate", + "description": "Vectorized arrays, DataFrames, cleaning, grouping and joining data.", + "prerequisites": ["data-structures", "statistics"], "key_concepts": ["ndarray and broadcasting", "DataFrame indexing", "missing values", "groupby/aggregate", "merge/join"]}, + {"slug": "ml-basics", "name": "Machine Learning Basics", "category": "AI/ML", "difficulty": "intermediate", + "description": "Supervised vs unsupervised learning, regression, classification and scikit-learn.", + "prerequisites": ["numpy-pandas"], "key_concepts": ["supervised vs unsupervised", "linear/logistic regression", "train/test split", "overfitting", "scikit-learn API"]}, + {"slug": "model-evaluation", "name": "Model Evaluation", "category": "AI/ML", "difficulty": "intermediate", + "description": "Metrics, cross-validation, bias-variance trade-off and hyperparameter tuning.", + "prerequisites": ["ml-basics"], "key_concepts": ["accuracy/precision/recall/F1", "ROC-AUC", "cross-validation", "bias-variance", "grid/random search"]}, + {"slug": "neural-networks", "name": "Neural Networks", "category": "AI/ML", "difficulty": "advanced", + "description": "Perceptrons, activation functions, backpropagation and gradient descent.", + "prerequisites": ["ml-basics"], "key_concepts": ["perceptron", "activation functions", "loss functions", "backpropagation", "gradient descent variants"]}, + {"slug": "deep-learning-pytorch", "name": "Deep Learning with PyTorch", "category": "AI/ML", "difficulty": "advanced", + "description": "Tensors, autograd, nn.Module, training loops, CNNs and GPU training.", + "prerequisites": ["neural-networks"], "key_concepts": ["tensors and autograd", "nn.Module", "training loop", "CNNs", "GPU / mixed precision"]}, + {"slug": "nlp-transformers", "name": "NLP & Transformers", "category": "AI/ML", "difficulty": "advanced", + "description": "Tokenization, embeddings, attention and the transformer architecture.", + "prerequisites": ["deep-learning-pytorch"], "key_concepts": ["tokenization", "embeddings", "self-attention", "encoder vs decoder", "fine-tuning"]}, + {"slug": "llm-agents", "name": "LLM Apps & Agents", "category": "AI/ML", "difficulty": "advanced", + "description": "Prompting, RAG, tool calling and multi-agent orchestration with LangGraph.", + "prerequisites": ["nlp-transformers", "rest-apis"], "key_concepts": ["prompt engineering", "retrieval-augmented generation", "tool/function calling", "agent graphs (LangGraph)", "evaluation and guardrails"]} + ] +} diff --git a/backend/curriculum/seed.py b/backend/curriculum/seed.py new file mode 100644 index 0000000000000000000000000000000000000000..365c0819e4280c9444a9ee71099375ae19a59756 --- /dev/null +++ b/backend/curriculum/seed.py @@ -0,0 +1,46 @@ +"""Idempotent seeding of the curriculum and the starter question bank.""" +import json +import os + +from models import Topic, db +from services.content import add_questions + +HERE = os.path.dirname(os.path.abspath(__file__)) + + +def seed_curriculum(): + with open(os.path.join(HERE, 'curriculum.json')) as f: + topics = json.load(f)['topics'] + + # Upsert by slug, falling back to name so v1 databases keep their topic IDs. + rows = {} + for pos, t in enumerate(topics): + row = Topic.query.filter_by(slug=t['slug']).first() or Topic.query.filter_by(name=t['name']).first() + if row is None: + row = Topic(name=t['name']) + db.session.add(row) + row.slug, row.name, row.category = t['slug'], t['name'], t['category'] + row.difficulty, row.description = t['difficulty'], t['description'] + row.key_concepts, row.position = t['key_concepts'], pos + rows[t['slug']] = row + db.session.flush() + for t in topics: + rows[t['slug']].prerequisites = ','.join(str(rows[p].id) for p in t['prerequisites']) + db.session.commit() + return rows + + +def seed_questions(rows): + with open(os.path.join(HERE, 'seed_questions.json')) as f: + bank = json.load(f) + added = 0 + for slug, questions in bank.items(): + if slug in rows: + added += len(add_questions(rows[slug].id, questions, source='seed')) + db.session.commit() + return added + + +def seed_all(): + rows = seed_curriculum() + return seed_questions(rows) diff --git a/backend/curriculum/seed_questions.json b/backend/curriculum/seed_questions.json new file mode 100644 index 0000000000000000000000000000000000000000..3104cb42f44d7c315e3f8de86116d415921f6c00 --- /dev/null +++ b/backend/curriculum/seed_questions.json @@ -0,0 +1,222 @@ +{ + "python-basics": [ + {"difficulty": "beginner", "concept": "type conversion", "question": "What does int(\"7\") + 3 evaluate to?", + "options": {"A": "10", "B": "\"73\"", "C": "TypeError", "D": "7.3"}, "correct_answer": "A", + "explanation": "int(\"7\") converts the string to the integer 7, so 7 + 3 = 10."}, + {"difficulty": "intermediate", "concept": "operators", "question": "What is the value of 17 // 5 and 17 % 5 respectively?", + "options": {"A": "3.4 and 2", "B": "3 and 2", "C": "3 and 3", "D": "4 and 2"}, "correct_answer": "B", + "explanation": "// is floor division (17 // 5 = 3) and % gives the remainder (17 % 5 = 2)."}, + {"difficulty": "advanced", "concept": "mutability", "question": "Given a = [1, 2]; b = a; b.append(3) β€” what is a?", + "options": {"A": "[1, 2]", "B": "[1, 2, 3]", "C": "[3]", "D": "Error"}, "correct_answer": "B", + "explanation": "b = a binds a second name to the same list object, so mutating b also changes a."} + ], + "control-flow": [ + {"difficulty": "beginner", "concept": "range()", "question": "How many times does `for i in range(2, 8):` loop?", + "options": {"A": "8", "B": "7", "C": "6", "D": "5"}, "correct_answer": "C", + "explanation": "range(2, 8) yields 2, 3, 4, 5, 6, 7 β€” six values; the stop value is excluded."}, + {"difficulty": "intermediate", "concept": "list comprehensions", "question": "What does [x * x for x in range(5) if x % 2 == 0] produce?", + "options": {"A": "[0, 4, 16]", "B": "[1, 9]", "C": "[0, 1, 4, 9, 16]", "D": "[4, 16]"}, "correct_answer": "A", + "explanation": "The even values 0, 2, 4 are kept and squared: [0, 4, 16]."}, + {"difficulty": "advanced", "concept": "loop else", "question": "When does the `else` block of a Python `for` loop run?", + "options": {"A": "Only when the loop body raises an exception", "B": "When the loop finishes without hitting `break`", "C": "Every time the condition is false", "D": "Never; it is a syntax error"}, "correct_answer": "B", + "explanation": "A loop's else clause runs once after normal completion and is skipped if the loop exits via break."} + ], + "functions": [ + {"difficulty": "beginner", "concept": "return", "question": "What does a Python function return if it has no return statement?", + "options": {"A": "0", "B": "An empty string", "C": "None", "D": "It raises an error"}, "correct_answer": "C", + "explanation": "Functions without an explicit return implicitly return None."}, + {"difficulty": "intermediate", "concept": "*args/**kwargs", "question": "In def f(*args, **kwargs), calling f(1, 2, x=3) gives args and kwargs equal to:", + "options": {"A": "[1, 2] and {'x': 3}", "B": "(1, 2) and {'x': 3}", "C": "(1, 2, 3) and {}", "D": "(1, 2) and ('x', 3)"}, "correct_answer": "B", + "explanation": "Positional extras are collected into a tuple and keyword extras into a dict."}, + {"difficulty": "advanced", "concept": "default and keyword args", "question": "Why is `def add(item, bucket=[])` a common bug?", + "options": {"A": "Lists cannot be default values", "B": "The default list is created once and shared across calls", "C": "bucket becomes a tuple", "D": "It makes the function recursive"}, "correct_answer": "B", + "explanation": "Default values are evaluated once at definition time, so the same list accumulates items across calls. Use bucket=None instead."} + ], + "data-structures": [ + {"difficulty": "beginner", "concept": "lists vs tuples", "question": "Which of these is immutable?", + "options": {"A": "list", "B": "dict", "C": "set", "D": "tuple"}, "correct_answer": "D", + "explanation": "Tuples cannot be modified after creation; lists, dicts and sets are mutable."}, + {"difficulty": "intermediate", "concept": "dict lookups", "question": "What is the average time complexity of `key in my_dict`?", + "options": {"A": "O(1)", "B": "O(log n)", "C": "O(n)", "D": "O(n log n)"}, "correct_answer": "A", + "explanation": "Dictionaries are hash tables, so membership checks are O(1) on average."}, + {"difficulty": "advanced", "concept": "stack/queue (deque)", "question": "Why prefer collections.deque over list for a FIFO queue?", + "options": {"A": "deque supports indexing faster", "B": "list.pop(0) is O(n) while deque.popleft() is O(1)", "C": "deque uses less memory per item", "D": "lists cannot hold mixed types"}, "correct_answer": "B", + "explanation": "Removing from the front of a list shifts every element (O(n)); a deque pops from either end in O(1)."} + ], + "oop": [ + {"difficulty": "beginner", "concept": "class and __init__", "question": "What is the role of __init__ in a Python class?", + "options": {"A": "It deletes the object", "B": "It initializes a newly created instance", "C": "It defines a class constant", "D": "It imports the class"}, "correct_answer": "B", + "explanation": "__init__ runs right after an instance is created and sets up its initial attributes."}, + {"difficulty": "intermediate", "concept": "inheritance and super()", "question": "What does super().__init__(name) do inside a subclass __init__?", + "options": {"A": "Creates a new parent object", "B": "Calls the parent class initializer on the current instance", "C": "Copies the parent's methods", "D": "Makes the class abstract"}, "correct_answer": "B", + "explanation": "super() delegates to the next class in the MRO so the parent's initialization runs on self."}, + {"difficulty": "advanced", "concept": "dunder methods", "question": "Which method should you implement so that len(obj) works?", + "options": {"A": "__size__", "B": "__count__", "C": "__len__", "D": "__length__"}, "correct_answer": "C", + "explanation": "The built-in len() calls the object's __len__ method."} + ], + "error-handling-testing": [ + {"difficulty": "beginner", "concept": "try/except/else/finally", "question": "When does a `finally` block run?", + "options": {"A": "Only if an exception occurs", "B": "Only if no exception occurs", "C": "Always, whether or not an exception occurs", "D": "Only when re-raising"}, "correct_answer": "C", + "explanation": "finally always executes, making it the right place for cleanup code."}, + {"difficulty": "intermediate", "concept": "raising exceptions", "question": "Which is the best way to signal an invalid argument value?", + "options": {"A": "return -1", "B": "print('error')", "C": "raise ValueError('...')", "D": "exit()"}, "correct_answer": "C", + "explanation": "Raising ValueError communicates the problem explicitly and lets callers handle it."}, + {"difficulty": "advanced", "concept": "pytest basics", "question": "How do you assert that a function raises ZeroDivisionError in pytest?", + "options": {"A": "assert f() == ZeroDivisionError", "B": "with pytest.raises(ZeroDivisionError): f()", "C": "pytest.expect(f, ZeroDivisionError)", "D": "try: f() except: pass"}, "correct_answer": "B", + "explanation": "pytest.raises is a context manager that fails the test unless the expected exception is raised."} + ], + "algorithms": [ + {"difficulty": "beginner", "concept": "binary search", "question": "Binary search requires the input to be:", + "options": {"A": "Sorted", "B": "Unique", "C": "Numeric", "D": "Of even length"}, "correct_answer": "A", + "explanation": "Binary search halves the range by comparing with the middle element, which only works on sorted data."}, + {"difficulty": "intermediate", "concept": "merge/quick sort", "question": "What is the worst-case time complexity of merge sort?", + "options": {"A": "O(n)", "B": "O(n log n)", "C": "O(n^2)", "D": "O(log n)"}, "correct_answer": "B", + "explanation": "Merge sort always splits in half (log n levels) and merges in linear time per level."}, + {"difficulty": "advanced", "concept": "two pointers and sliding window", "question": "Finding the longest substring without repeating characters is best solved in:", + "options": {"A": "O(n^3) brute force only", "B": "O(n) with a sliding window and a hash map", "C": "O(n log n) by sorting", "D": "O(1) with recursion"}, "correct_answer": "B", + "explanation": "A sliding window that tracks the last index of each character visits each character a constant number of times."} + ], + "web-fundamentals": [ + {"difficulty": "beginner", "concept": "HTML elements", "question": "Which HTML element creates a hyperlink?", + "options": {"A": "", "B": "", "C": "", "D": "