AI Career Advisor

An open, end‑to‑end AI career development platform: modern React frontend + FastAPI backend with multi‑agent orchestration (Career Analyst, Mentor Bot, Skills Assessor, Learning Orchestrator, Opportunity Scout, Progress Monitor). Uses Google Gemini via an LLM layer to run assessments (Big Five, RIASEC), generate recommendations, and power interactive counseling and analytics.

Quick Start • Features • Architecture • Configuration • API • Roadmap • Contributing

---

Badges

---

✨ Features

• Assessments: Big Five personality, RIASEC interests, skills gap analysis
• Career Matching: Fit scoring, reasoning, and recommended actions
• Mentor Chat: Sentiment‑aware, context memory, actionable next steps
• Analytics: Career trends, skill demand predictions, disruption insights
• Progress Tracking: Goals, milestones, achievements
• Full Monorepo: React + TS + Vite frontend, FastAPI backend, data models & agents

---

🏗 Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    AI CAREER ADVISOR SYSTEM                                 │
│                                                                             │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐        │
│  │   React Frontend │    │  FastAPI Backend │    │  Google Gemini  │        │
│  │   (Port 3000)    │◄──►│   (Port 8001)    │◄──►│    AI Model     │        │
│  │  • Dashboard     │    │  • REST APIs     │    │  • LLM Calls    │        │
│  │  • Chat UI       │    │  • Agent Router  │    │  • Analysis     │        │
│  │  • Analytics     │    │  • Database      │    │  • Counseling   │        │
│  │  • Profiles      │    │  • Auth          │    │                 │        │
│  └─────────────────┘    └─────────────────┘    └─────────────────┘        │
└─────────────────────────────────────────────────────────────────────────────┘

Agents

• CareerAnalyst • MentorBot • SkillsAssessor • LearningOrchestrator • OpportunityScout • ProgressMonitor

Tech Stack

• Frontend: React 19 + TypeScript + Vite, React Router, Recharts
• Backend: FastAPI, LangChain‑based agent framework, SQLite (async)
• LLM: Google Gemini (configurable)

---

📁 Monorepo Structure

manaspros-aicareer/
├─ career-advisor-frontend/      # React + TS + Vite app
│  └─ src/components/...         # Dashboard, Chat, Analytics, Profile, etc.
├─ career_advisor_agents/        # FastAPI service + agents
│  ├─ api/                       # routes, main
│  ├─ agents/                    # career_analyst.py, mentor_bot.py, ...
│  ├─ core/                      # agent_framework.py, llm_config.py
│  ├─ services/                  # counseling, predictive_analytics, db
│  ├─ data/                      # skills_taxonomy.json, industry_trends.json
│  ├─ run_server.py              # entrypoint
│  └─ requirements.txt / pyproject.toml
├─ SYSTEM_WORKFLOW.md            # end‑to‑end flow & endpoints
└─ CLAUDE.md                     # prompts/settings (placeholder)

---

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.11+

1) Backend (FastAPI)

cd career_advisor_agents
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your keys (see Configuration below)
python run_server.py   # serves on http://localhost:8001

2) Frontend (React + Vite)

cd career-advisor-frontend
npm install
# set VITE_API_BASE_URL in a .env file if different from default
npm run dev   # http://localhost:3000

3) Open the App

Visit http://localhost:3000. The app performs a health check and can auto‑create a demo user. Use the Dashboard to explore Profile, Chat, Career Analysis, and Analytics.

---

⚙️ Configuration

Backend .env

GEMINI_API_KEY=your_key_here
DATABASE_URL=sqlite+aiosqlite:///career.db
CORS_ALLOWED_ORIGINS=http://localhost:3000
PORT=8001

Frontend .env

VITE_API_BASE_URL=http://localhost:8001

Tip: secure secrets via your preferred secret manager in production.

---

🔌 API Overview

Health & System

• GET /health — system health
• GET /api/system/agents — list available agents
• GET /api/system/metrics — performance metrics

Users

• POST /api/users/register — register new user
• GET /api/users/{user_id}/profile • PUT /api/users/{user_id}/profile

Agents

• POST /api/agents/career-analysis — run assessments & matching
• POST /api/agents/counseling/chat — mentor chat
• GET /api/agents/recommendations/{user_id} — personalized recs

Analytics

• GET /api/analytics/career-trends
• GET /api/analytics/skill-demand
• GET /api/analytics/market-predictions

Conversations

• GET /api/conversations/{user_id}

---

🗄 Data Model (high level)

• users (profile, education level, career stage)
• conversations (messages, agent, context, confidence)
• personality_assessments (OCEAN traits)
• interest_assessments (RIASEC)
• career_recommendations (title, score, actions)
• progress_updates (skills, goals, milestones)

---

🔒 Security & Privacy

• Data encryption at rest, rate limiting, privacy controls, audit logging
• Conversation memory with explicit user controls

---

🧪 Status

Working: Frontend UI, FastAPI endpoints, DB layer (SQLite async), agent framework, Gemini config

Known Issues

1. Some agents still return hardcoded responses
2. Enum validation edge cases in DB
3. LLM errors fallback to dummy responses

---

🗺 Roadmap

• Agent routing fixes to consistently use AI
• Stronger error handling & logging
• Enhanced prompt engineering
• Proper scoring algorithms for assessments
• Real‑time market data integration

---

🤝 Contributing

1. Fork & create a feature branch
2. Follow TypeScript/Python linters
3. Open a PR with a clear description & screenshots where relevant

---

📄 License

TBD. Add a LICENSE file (MIT/Apache‑2.0 recommended) and update the badge.

---

🙌 Acknowledgements

• React, Vite, FastAPI, LangChain, Google Gemini, Recharts

Built for learners, job seekers, and career switchers who want actionable, AI‑assisted guidance end‑to‑end.