An academic wellbeing and career co-pilot for college students: ML risk detection with human-counselor escalation, plus an AI career planner.
NexusAI is a full-stack platform that helps colleges spot students who are struggling and connect them with support before things get worse. It also helps those same students plan their careers. It does two things:
- Wellbeing monitoring: an ML pipeline watches behavioral signals and chat sentiment, scores a student's risk, and escalates high-risk cases to a human counselor with an alert.
- Career guidance: a separate agent parses a resume, finds skill gaps, builds a 12-week roadmap, runs mock interviews, and recommends jobs.
There are two roles. Students get a dashboard, a chat assistant (MindBridge), and the career planner (PathwayAI). Counselors get an alert feed filtered by risk tier, with case notes and a resolution workflow that notifies the student when a case is closed.
I built this solo: the backend, the frontend, the ML pipeline, the agent layer, and the infrastructure. It is the most complete project I've shipped: a Dockerized FastAPI backend with async SQLAlchemy and Alembic migrations, a React/TypeScript frontend, four MCP microservices, and pytest and vitest suites. The repo has roughly 5,100 lines of Python plus the TypeScript frontend. Nothing in it has been validated on real students.
- Behavioral anomaly detection: an IsolationForest model scores a 7-dimensional behavior vector (session-gap days, survey-skip streak, average session length, assignment-delay hours, chat-initiation frequency, mood-score trend, login-hour variance), trained on 2,000 synthetic normal-behavior samples (seed 42, 5% contamination).
- Sentiment / distress scoring: DistilBERT (
distilbert-base-uncased-finetuned-sst-2-english) scores each student message, capped at 512 tokens. - Weighted risk fusion: anomaly, sentiment, and survey-decline signals combine into one risk score,
0.50·anomaly + 0.35·sentiment + 0.15·survey_decline, bucketed into four tiers (Low / Moderate / High / Crisis). - Three-signal crisis gate: a multi-stage gate (explicit keyword match plus a corroborating signal, high fused score, or two-signal convergence) decides when to escalate, with negation-window checks and fiction-context filtering to cut false positives on crisis keywords.
- Multi-agent routing: an orchestrator routes each request to the Crisis, Wellbeing, or Pathway agent based on risk score and keyword matching.
- Hybrid LLM stack: Ollama is the primary model (3s timeout), with a hosted-API fallback (25s timeout) behind a circuit breaker, so the system keeps answering if the local model is slow or down. The fallback module is named for Claude but actually calls OpenAI (see Getting Started).
- RAG over curated resources: SentenceTransformers embeddings indexed in FAISS (inner-product) serve career and academic recommendations (courses, government schemes, job sites). The index is built on first startup if missing.
- Voice chat: students can upload audio, and Whisper transcribes it before it enters the pipeline.
- PathwayAI career planner: resume PDF parsing, skill extraction, a skill-gap radar, a 12-week roadmap, and a 5-question progressive mock interview.
- Counselor dashboard: an alert feed filterable by risk threshold, a per-student risk/anomaly/sentiment breakdown, case notes, and a resolve-with-notification workflow.
- Four MCP microservices: student-db, job-market, resource-rag, and counselor-alerts servers (ports 9001–9004), each a small FastAPI service.
- Backend plumbing: JWT auth with a token revocation table, per-IP rate limiting (slowapi), CORS, DB connection retry on startup, background ML pre-warming, and periodic context-store cleanup.
Each student produces a 7-dimensional behavior vector. The features are scaled to fixed ranges (for example session_gap_days 0–30, mood_score_trend -5 to 5) so the model sees consistent input. Mood surveys use a PHQ-inspired 3-question format (feeling, energy, motivation on a 1–10 scale) and produce a composite score that feeds the survey-decline signal.
The scorer (ml/risk/scorer.py) clamps each input to [0, 1] and computes the fused score directly:
score = 0.50 * anomaly + 0.35 * sentiment + 0.15 * survey_declineIt then assigns a tier: < 0.4 low, 0.4–0.6 moderate, 0.6–0.8 high, >= 0.8 crisis. The function returns the score, the tier, and the three component scores, so the frontend can show a per-signal breakdown instead of one opaque number. The weights are fixed by hand.
| Tier | Score | Action |
|---|---|---|
| Low | < 0.4 | No action; default to career guidance |
| Moderate | 0.4 – 0.6 | Wellbeing agent gives empathetic support |
| High | 0.6 – 0.8 | Counselor encouraged + iCall helpline shown |
| Crisis | >= 0.8 | Three-signal gate + counselor alert + helpline |
Crisis keyword matching is where false positives matter most, so it gets the most care. The detector (agents/orchestrator/router_logic.py) compiles 17 regex patterns with word boundaries (so "suicidal" matches but "antidote" does not), covering stem variants and common phrasings. On top of the raw regex match it adds two filters:
- Fiction-context filter: if the text mentions movie/game/book/lyrics-style tokens (including specific titles like "suicide squad" or "13 reasons") and has no first-person markers ("I am", "I feel", "my life"), the match is dropped.
- Negation window: for each match, the 5 words immediately before it are checked for negation words ("not", "never", "can't"…). Negated matches are not counted.
Only matches that survive both filters count toward the crisis gate, which combines them with the fused risk score and two-signal convergence rules.
The orchestrator routes in priority order:
- Confirmed crisis keywords or risk
>= 0.8→ Crisis agent - Career/pathway keywords (
job,resume,roadmap,internship,swayam,pmkvy, …) → Pathway agent - Risk
>= 0.4→ Wellbeing agent (MindBridge) - Otherwise → Pathway agent (career guidance is the default)
Pathway and wellbeing keyword matching are simple set lookups, since a false positive costs little there. The heavy false-positive handling is reserved for the crisis path.
Generation goes through a router in agents/llm that tries Ollama first with a 3-second timeout. If that fails, the circuit breaker stops using Ollama for 300 seconds and hands off to the hosted fallback with a 25-second timeout. This keeps latency low in the common case and still produces an answer when the local model isn't available.
Curated career and academic resources are embedded with SentenceTransformers (3.3.1) and stored in a FAISS IndexFlatIP. Retrieval is top-k inner-product search with domain filtering, so a career query pulls back courses, schemes and job sites rather than wellbeing content. The index lives at rag/data/faiss_index/nexus.index. It is gitignored and built automatically on first run if it doesn't exist.
The FastAPI app (backend/src/main.py) wires this together. On startup it retries the DB connection up to 5 times, creates tables, prunes expired revoked tokens, ensures the RAG index exists, pre-warms the ML models in a background task so the first real request isn't slow, and starts a 30-minute loop that evicts stale entries from the agent context store. Requests are rate-limited per client IP.
The React 18 / TypeScript frontend (Vite, Tailwind, TanStack Query, Zustand) renders the student dashboard with a risk gauge, a 30-day mood-history chart, a per-signal breakdown, and a check-in streak counter (Recharts). MindBridge is the chat view with tier-calibrated responses, signal visualization, voice upload, and the iCall helpline for high and crisis tiers. PathwayAI handles resume upload, the skill radar, the roadmap, and mock interviews. The counselor dashboard is a separate route with the alert feed and case workflow. The Vite dev server proxies /api to the backend at localhost:8000.
This is a working system rather than a benchmarked model, so most of the numbers below are design parameters, not measured metrics:
- IsolationForest trained on 2,000 synthetic samples, 5% contamination, fixed seed 42 for reproducibility.
- Risk fusion weights 0.50 / 0.35 / 0.15 across anomaly, sentiment, and survey signals; four tiers.
- 17 crisis regex patterns plus negation-window and fiction-context filtering on the escalation path.
- DistilBERT sentiment scoring capped at 512 tokens; Ollama (3s) with a hosted fallback (25s).
- About 5,100 lines of Python (agents, backend, ML, RAG, MCP servers) plus the React/TypeScript frontend, with pytest tests (
test_auth_service,test_risk_scorer,test_router_logic), vitest tests for the frontend, Alembic migrations, and Dockerfiles. The repo has no CI workflow. - Target goals stated in the design, not measured: under 5% crisis false-positive rate and wider counselor coverage per case.
- Languages: Python 3.11+, TypeScript 5.4
- Backend / API: FastAPI 0.123, Uvicorn, SQLAlchemy 2.0 (async) + asyncpg, Alembic, python-jose (JWT), passlib (bcrypt), slowapi, pydantic-settings, httpx
- ML / NLP: scikit-learn (IsolationForest), HuggingFace Transformers + PyTorch (DistilBERT), Whisper, sentence-transformers 3.3.1, FAISS
- LLM: Ollama (primary), hosted API fallback behind a circuit breaker
- Frontend: React 18, Vite 5, Tailwind CSS 3, Recharts, TanStack React Query, Zustand, Lucide
- Infra: PostgreSQL 15, Docker + Docker Compose, four MCP microservices,
uvpackage manager
- Python 3.11+
- Node.js 18+ and npm
uv(Python package manager)- Docker and Docker Compose (for the full-stack run)
- PostgreSQL 15 (if running the backend locally without Docker)
git clone https://github.com/DCode-v05/NexusAI.git
cd NexusAI
cp .env.example .env # then edit .env (DB URL, secret key, API keys)SECRET_KEY must be replaced. The app refuses to start with the example value. Generate one with python -c "import secrets; print(secrets.token_hex(32))".
Backend:
cd backend
uv sync
uv run alembic upgrade head
uv run python scripts/seed_demo.py # optional: seed demo data
uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reloadFrontend:
cd frontend
npm install
npm run devdocker compose up --build # start backend, frontend (port 3000), MCP servers, and PostgreSQL
docker compose down # stop everythingcd backend && uv run pytest
cd frontend && npm run test:unit:run| Variable | Description |
|---|---|
DATABASE_URL |
PostgreSQL connection string (asyncpg) |
SECRET_KEY |
JWT signing key (32+ chars) |
OLLAMA_BASE_URL |
Ollama server URL |
OLLAMA_MODEL |
Ollama model name |
ANTHROPIC_API_KEY |
Key for the fallback LLM. Despite the name, agents/llm/claude_fallback.py posts to the OpenAI chat completions endpoint (gpt-4o-mini) with this value, so it needs an OpenAI key. |
- Students log in to the dashboard for a live view of their wellbeing signals and risk score, with mood history and a per-signal breakdown.
- MindBridge is the chat assistant. Students talk to it normally and get tier-calibrated responses, with crisis escalation and the iCall helpline shown automatically when the risk tier warrants it. Voice messages are transcribed by Whisper before they enter the pipeline.
- PathwayAI handles career planning: upload a resume, get extracted skills and a skill-gap radar, generate a 12-week roadmap, and run a 5-question mock interview.
- Counselors work the alert feed: filter by risk threshold, open a student card to see the anomaly/sentiment breakdown, add case notes, and resolve cases, which notifies the student.
NexusAI/
├── agents/ # Orchestration + specialist agents
│ ├── orchestrator/ # Router (router_logic.py), context store
│ ├── crisis/ # Crisis intervention agent
│ ├── wellbeing/ # MindBridge wellbeing agent
│ ├── pathway/ # Career guidance agent
│ └── llm/ # Ollama client + hosted fallback (claude_fallback.py)
├── ml/
│ ├── anomaly/ # IsolationForest detector + 7-feature builder
│ ├── sentiment/ # DistilBERT analyzer + preprocessor
│ ├── risk/ # Weighted risk scorer (scorer.py)
│ └── speech/ # Whisper transcription
├── rag/ # Embedder, FAISS indexer, retriever, resource DB
│ └── scripts/build_index.py # Index builder
├── backend/ # FastAPI service
│ ├── src/
│ │ ├── auth/ # JWT auth + token revocation
│ │ ├── students/ # Student profiles & behavior
│ │ ├── wellbeing/ # Alerts & chat APIs
│ │ ├── pathway/ # Career pathway APIs
│ │ ├── counselor/ # Counselor dashboard APIs
│ │ ├── shared/ # Utils & exceptions
│ │ └── main.py # App entry: lifespan, rate limit, warmup
│ ├── alembic/ # Migrations
│ ├── scripts/seed_demo.py # Demo seed
│ └── tests/ # pytest: auth, risk scorer, router logic
├── mcp-servers/ # Four FastAPI MCP services (ports 9001–9004)
│ ├── student-db-server/
│ ├── job-market-server/
│ ├── resource-rag-server/
│ └── counselor-alerts-server/
├── frontend/ # React 18 + TypeScript (Vite, Tailwind)
│ └── src/
│ ├── pages/ # auth / student / counselor
│ ├── components/ # charts, chat, layout, ui
│ ├── api/ # API client layer
│ ├── hooks/ · store/ # hooks, Zustand stores
│ └── tests/ # vitest unit tests
├── shared/ # small shared utilities
├── docs/NexusAI-Overview.md # Extended design write-up
├── docker-compose.yml # Multi-service orchestration
├── .env.example # Environment template
└── README.md
| Portfolio: Denistan | LinkedIn: denistanb |
| GitHub: DCode-v05 | LeetCode: Denistan_B |
| Email: denistanb05@gmail.com | |
Made with ❤️ by Denistan B