Skip to content

progress.md

Latest commit

 

History

History
677 lines (481 loc) · 17.6 KB

progress.md

File metadata and controls

677 lines (481 loc) · 17.6 KB
Raw

Phase 3 — Skill Intelligence Engine

Objective

Build a deterministic Skill Intelligence Engine using only:

  • Python
  • Flask
  • SQLAlchemy
  • SQLite
  • Existing Phase 2 student data

No AI models or external AI APIs are required.

The system should convert student data into:

Assessment → Proficiency → Evidence → Skill Score → Skill Gaps → Role Matching → Recommendations

1. Skill Assessment

Implement:

  • Assessment
  • Assessment questions
  • Student attempts
  • Student answers
  • Assessment results
  • Skill-wise scores

Assessment scoring must be deterministic.

Normalize scores to a 0–100 range.

Example:

Correct answers / Total questions × 100

2. Proficiency Score

Create a centralized proficiency calculation service.

Use existing StudentSkill data and assessment results.

Keep the calculation deterministic and explainable.

Do not use AI or ML.

3. Evidence Score

Use existing:

  • Projects
  • Certifications
  • Experience
  • Internships
  • Skill Evidence
  • Resume-derived structured information where available

Assign configurable weights to evidence types.

Example:

Project       → 25
Certification → 20
Experience    → 30
Internship    → 30
Verified evidence → additional weight where appropriate

Keep all weights centralized.

Do not invent evidence.

4. Overall Skill Score

Calculate an overall skill score from structured information.

Initial formula:

60% × Proficiency
40% × Evidence Strength

Keep the weights configurable.

Return:

{
  "skill": "Python",
  "proficiency_score": 80,
  "evidence_score": 70,
  "overall_score": 76
}

All calculations must be deterministic.

5. Target Roles

Create a role system.

A role should contain:

  • Role name
  • Description
  • Required skills
  • Skill weights
  • Minimum required proficiency

Examples:

Backend Developer
Software Engineer
Frontend Developer
Data Analyst
Data Scientist

Do not hardcode role logic inside Flask routes.

6. Role Matching

Calculate role compatibility using the student's existing skill scores.

Example:

Python       → 80
SQL          → 70
Flask        → 85
Docker       → 40

For each role, compare the student's skill score against the required skill score.

Use a deterministic weighted formula.

Example:

Role Match =
Σ(student_skill_score × skill_weight)
---------------------------------------
Σ(skill_weight)

Return the contributing skills and scores.

Do not use AI or ML.

7. Skill Gap Detection

For the selected target role:

Required Score - Student Score = Gap

Example:

SQL:
Required = 75
Student = 55
Gap = 20

Classify gaps:

0       → Meets requirement
1–10    → Minor gap
11–25   → Moderate gap
26+     → Major gap

The thresholds should be configurable.

Also identify completely missing required skills.

8. Learning Recommendations

Create a rule-based recommendation system.

No AI.

No ML.

No external API.

Recommendations should be generated from skill gaps.

Example:

Python gap
→ Python fundamentals

SQL gap
→ SQL joins, aggregation, subqueries

DSA gap
→ Arrays, hashing, linked lists, trees

Flask gap
→ Flask routing, REST APIs, authentication

Docker gap
→ Containers, images, Dockerfiles

Store recommendation data in structured configuration or database tables rather than putting large rules inside routes.

9. REST APIs

Expose the Phase 3 functionality through the existing Flask REST architecture.

Suggested endpoints:

/api/assessments
/api/skills/scores
/api/skill-gaps
/api/roles
/api/role-matches
/api/recommendations

Follow the existing:

  • JWT authentication
  • Authorization
  • Marshmallow validation
  • Service layer
  • Error handling
  • HTTP status conventions

10. Database

Create only the models required for Phase 3.

Possible models:

  • Assessment
  • AssessmentQuestion
  • AssessmentAttempt
  • AssessmentAnswer
  • Role
  • RoleSkillRequirement
  • LearningRecommendation

Reuse all existing Phase 2 models.

Do not duplicate:

  • StudentProfile
  • Skill
  • StudentSkill
  • Project
  • Certification
  • Experience
  • Internship
  • SkillEvidence
  • Resume

Create migrations for new models.

11. Architecture

Maintain:

Routes
   ↓
Schemas
   ↓
Services
   ↓
Business Logic
   ↓
Models / Database

Keep scoring and matching logic inside dedicated services.

Do not put business logic directly in route functions.

12. Testing

Create tests for:

  • Assessment creation
  • Assessment submission
  • Assessment scoring
  • Proficiency calculation
  • Evidence scoring
  • Overall skill score
  • Role creation
  • Role requirements
  • Role matching
  • Skill gap detection
  • Missing skills
  • Recommendations
  • Authorization
  • Validation
  • Boundary scores
  • Empty data
  • Invalid data

Run the complete existing test suite as regression testing.

Phase 1 and Phase 2 functionality must continue passing.

13. No AI / ML Requirement

This project intentionally does NOT use:

  • Claude
  • OpenAI
  • Gemini
  • Sentence Transformers
  • Hugging Face models
  • Embeddings
  • Machine-learning models
  • External AI APIs
  • Paid APIs

The intelligence layer is implemented using:

  • deterministic formulas
  • weighted scoring
  • configurable thresholds
  • database-driven rules
  • rule-based recommendations

The system must remain fully functional without an AI model or external AI service.

Phase 3 Checklist

  • Assessment model
  • Assessment questions
  • Assessment attempts
  • Assessment answers
  • Assessment scoring
  • Proficiency scoring
  • Evidence scoring
  • Overall skill score
  • Role model
  • Role skill requirements
  • Role matching
  • Skill gap detection
  • Rule-based recommendations
  • REST APIs
  • Validation
  • Authorization
  • Database migrations
  • Unit tests
  • API tests
  • Full regression tests
  • Documentation

Current Status

Phase 1

Completed and committed.

Phase 2

Completed and committed.

Phase 3

Implemented and regression tested. See backend/README.md for formulas and API behavior.

Phase 4A — Free/Local AI Backend

Objective

Add a free/local AI backend layer for generative tasks that benefit from natural-language reasoning.

The AI layer must operate on top of the deterministic Phase 3 Skill Intelligence Engine.

The AI layer must NOT replace or modify deterministic Phase 3 calculations.

AI-supported features

  • Resume skill extraction
  • Skill normalization suggestions
  • Skill-gap explanations
  • Personalized learning roadmap generation

Deterministic Phase 3 responsibilities remain unchanged

The AI layer must NOT calculate:

  • Skill scores
  • Proficiency scores
  • Evidence scores
  • Semantic similarity
  • Role-match percentages
  • Numerical skill gaps
  • Assessment scores

These remain handled by the Phase 3 deterministic services.

Free/Local AI Backend

  • Local AI service abstraction
  • Local model/runtime integration
  • No paid external AI API
  • No API key requirement
  • Request timeout handling
  • Model/runtime error handling
  • Safe structured response parsing
  • AI response validation
  • Graceful fallback when local AI is unavailable
  • AI model configuration kept separate from routes

APIs

  • Resume skill extraction API
  • Skill normalization API
  • Skill-gap explanation API
  • Personalized roadmap API

Testing

  • Successful AI response
  • Mocked AI response
  • Malformed response handling
  • Timeout handling
  • Model/runtime failure handling
  • Missing model/runtime handling
  • Fallback behavior
  • Authentication/authorization
  • Phase 3 regression tests

Requirements

The application must remain fully functional without the local AI model.

Phase 3 deterministic functionality must continue working even when the AI runtime or model is unavailable.

No Claude, Anthropic, OpenAI, Gemini, or other paid external AI API is required.

Phase 4A implementation notes

The architecture is AI routes → LocalAIService → OllamaAdapter → loopback Ollama runtime. The adapter uses Python's standard library HTTP client, and Flask does not load a model at startup. The default local model is qwen2.5:1.5b-instruct-q5_0; install Ollama and run ollama run qwen2.5:1.5b-instruct-q5_0 to enable local generation. Runtime URL, model name, timeout, and input limit are environment-configurable in backend/config.py and listed in backend/.env.example.

All four APIs are authenticated and student-scoped. Resume skills are catalog-matched suggestions with source evidence, are labeled unverified, and are never persisted by AI. Normalization must match an existing skill. Gap explanations and roadmaps receive Phase 3 results; their numeric scores, role match, and gaps are carried through unchanged. When the local runtime is unavailable or its output times out, is empty, malformed, or fails validation, the service returns a labeled deterministic fallback. Tests replace the adapter with mocked responses and do not download a model.

Current Status

Implemented and regression tested with an optional local Ollama runtime and Qwen2.5 1.5B instruct model. The backend starts and Phase 3 remains available without Ollama or downloaded models. See backend/README.md for setup, APIs, configuration, and fallback behavior.

Phase 4B — Frontend & Student Dashboard

Objective

Build the frontend interface for SkillBridge AI and connect it to the existing backend APIs from Phases 1–4A.

The frontend should present the student's profile, skills, assessments, skill scores, skill gaps, role matching, recommendations, and AI-powered insights through a clear and responsive dashboard.

The frontend must consume existing backend APIs rather than duplicating business logic.

Core Frontend

  • Frontend project setup
  • Responsive application layout
  • Navigation/sidebar
  • Authentication pages
  • Login
  • Registration
  • Protected routes
  • Student dashboard
  • Profile page
  • Skills page
  • Projects page
  • Certifications page
  • Experience/internships page

Skill Intelligence Dashboard

  • Overall skill score visualization
  • Individual skill scores
  • Proficiency scores
  • Evidence scores
  • Assessment interface
  • Assessment results
  • Skill-gap visualization
  • Missing required skills
  • Role matching results
  • Target-role selection
  • Rule-based learning recommendations

AI Features

Consume the Phase 4A APIs for:

  • Resume skill extraction
  • Skill normalization suggestions
  • Skill-gap explanations
  • Personalized learning roadmap

AI-generated information must be clearly distinguishable from verified/deterministic student data.

The frontend must not calculate:

  • Skill scores
  • Proficiency scores
  • Evidence scores
  • Skill gaps
  • Role-match percentages

All numerical intelligence must come from the backend.

API Integration

  • Centralized API client
  • JWT authentication handling
  • Authenticated API requests
  • Loading states
  • Empty states
  • Validation errors
  • API error handling
  • AI unavailable/fallback states
  • Session/logout handling

UX & Accessibility

  • Responsive design
  • Clear visual hierarchy
  • Accessible buttons and forms
  • Keyboard-friendly navigation
  • Form validation
  • Appropriate loading indicators
  • User-friendly error messages

Testing

  • Frontend component tests
  • Authentication flow testing
  • API integration testing
  • Protected-route testing
  • Assessment flow testing
  • Dashboard data rendering
  • Skill-gap rendering
  • AI fallback-state testing
  • Responsive layout testing (tablet/mobile breakpoint regression coverage)

Requirements

The frontend must work with the existing Flask backend.

Do not move backend business logic into the frontend.

Do not duplicate Phase 3 scoring or matching formulas in frontend code.

Do not expose local AI runtime configuration or model details unnecessarily to users.

Current Status

Phase 4B frontend is implemented. The frontend test suite passes (9 tests), and the Vite production build succeeds. Responsive tablet/mobile breakpoints have regression coverage. See frontend/README.md for setup and test commands.

Phase 5 development was subsequently authorized; see the implementation records below.

Phase 5A / 5B / 6 — integration (2026-09-29)

  • Added company profile, industry job/internship postings, skills and weights, student applications and tracking, candidate match details, ownership checks, shortlist actions, and industry dashboard.
  • Candidate matching reuses Phase 3 analyze_role; no second numeric scoring algorithm.
  • Added faculty profile, opportunity types, faculty applications and owner shortlisting; institution aggregate analytics scoped to a provisioned institution; student digital skill passport.
  • Added role-aware React screens, migration, demo seed, and setup instructions.
  • Verification: full backend suite, frontend tests and production build, migration on clean SQLite database. See root README for demo flow and limitations.

Phase 5A — Industry and Opportunities backend (2026-09-30)

Implementation completed on top of the existing Phase 5/6 integration.

  • Industry identity reuses User; company profile reuses CompanyProfile.
  • Job and internship CRUD with title, description, location, employment type, skill requirements/weights, eligibility text, deadline, stipend and duration.
  • Dedicated Marshmallow schemas with trimmed text, bounded fields, finite score/weight validation, strict skill IDs and malformed JSON handling.
  • Workflow business logic in OpportunityService; routes handle authentication, role guards, validation and serialization.
  • Students browse open postings, apply once and track only their applications.
  • Industry users manage only their postings and inspect only their applicants.
  • Candidate profiles include projects, certifications, experience and internships.
  • Matching delegates to the Phase 3 analyze_role engine; no second algorithm, numeric AI scoring, AI dependency or persisted duplicate Role records.
  • Candidate matching exposes the Phase 3 overall percentage, contributing skills, matching skills, gaps, stored evidence details and relevant projects.
  • Shortlisting and status transitions preserve the existing application tracker.
  • Closing a posting preserves application history; deadlines are inclusive.
  • Duplicate-application unique constraint and transaction rollback handling.
  • Tests for posting creation/editing, internships, validation, applications, deadlines, authorization/ownership, matching equivalence, evidence and shortlisting.
  • Backend API documentation updated in backend/README.md.

No new database models or migrations were needed: migration 6a29c9a56b71 already provides the tables. Existing frontend routes and response keys remain compatible. The additional GET /api/applications/:id endpoint is restricted to the posting owner. Eligibility is descriptive text; matching is live against current student data.

Verification: targeted Phase 5A and existing Phase 5/6 integration tests passed (34 tests). Full backend regression suite: 111 passed. Existing warnings concern SQLAlchemy legacy APIs and test JWT key length; no tests failed.

Phase 5B — Industry frontend (2026-09-30)

  • Replaced the basic industry screen with a role dashboard using existing React routes and API contracts; backend source was not modified for this phase.
  • Dashboard loads real industry summary, company profile, opportunities and skill catalog data; active jobs, internships, applications and shortlist counts are shown from /industry/summary.
  • Company profile editor and job/internship creation form use existing APIs, with dynamic required skills, proficiency targets, weights, eligibility and deadline.
  • Posting list supports search, type filters, applicants, and closing postings.
  • Applicant review uses server returned match percentages, skill requirements, gaps and evidence. Candidate drawer displays profile links, skill profile, projects, certifications and relevant experience.
  • Shortlisting calls /applications/:id/shortlist; status changes call the existing /applications/:id/status transition API.
  • Responsive tablet/mobile layout and accessibility labels added.
  • API integration tests cover summary loading, posting creation payload, candidate detail and shortlisting; responsive CSS has regression coverage.

Implementation uses the current React/Vite app and its shared SkillBridge design variables/components so the frontend can remain buildable without dependency changes. Tailwind CSS, shadcn/ui and Recharts are not installed in this project copy. Package installation could not be completed from the restricted npm registry environment; the opportunity distribution visualization is a small CSS chart based on live summary data. To adopt the specifically requested libraries, install them from a network-enabled environment and migrate these styles/chart. No fabricated candidate scores are present.

Verification: 21 frontend tests passed. Vite production build succeeded (52 modules). The test suite verifies API calls with mocked REST responses and checks the responsive CSS breakpoints; live browser/backend behavior still needs the local app running.