Skip to content
BranchesTags

Repository files navigation

🤖 Road2Work.id Machine Learning Service

Machine Learning Service Road2Work.id adalah service berbasis FastAPI yang menangani pemrosesan CV, speech-to-text, pembuatan pertanyaan interview adaptif, evaluasi jawaban interview, dan readiness insight.

Service ini dipanggil oleh backend, bukan langsung oleh frontend.

🧰 Tech Stack

  • Python
  • FastAPI
  • Uvicorn
  • Pydantic
  • OpenAI Responses API
  • faster-whisper
  • scikit-learn
  • TensorFlow / Keras
  • pandas
  • numpy
  • python-dotenv
  • PyMuPDF / PDF Text Extraction

📁 Struktur Folder

machine-learning/
├── main.py                         # FastAPI entry point
├── genai_helper.py                 # Helper GenAI untuk pertanyaan, evaluasi, feedback
├── readiness_engine.py             # Readiness scoring dan evaluasi jawaban
├── nlp_utils.py                    # NLP utility untuk ekstraksi profil dan skill
├── stt_utils.py                    # Speech-to-text utility
├── model_builder.py                # Training/building model utility
├── data/                           # Data kecil yang dibutuhkan service
├── models/                         # Model artifact lokal, sebagian di-ignore jika besar
├── scripts/                        # Script training/evaluation
├── requirements.txt                # Dependency Python
├── .env.example                    # Template environment
└── README_AI_ENGINEER.md

✨ Fungsi Utama

Service ini menangani beberapa proses utama pada Road2Work.id:

  • CV extraction
  • Short profile extraction
  • Role fit context generation
  • Adaptive interview question generation
  • Speech-to-text transcription
  • Answer quality evaluation
  • Clarification decision
  • Evidence ladder evaluation
  • Interview result generation
  • Readiness scoring support

🧭 Arsitektur Integrasi

Frontend tidak memanggil Machine Learning service secara langsung.

Frontend
→ Backend API
→ Machine Learning Service
→ Backend API
→ Frontend

📄 Contoh Flow Upload CV

Upload CV
→ Backend menerima file
→ Backend mengirim file ke ML service
→ ML service mengekstrak profil
→ Backend menyimpan hasil ke database
→ Frontend menampilkan profile review

🎙️ Contoh Flow Interview

User menjawab dengan suara
→ Frontend mengirim audio ke Backend
→ Backend mengirim audio ke ML service
→ ML service melakukan STT dan evaluasi jawaban
→ Backend menyimpan result
→ Frontend menampilkan next question atau result

✅ Prasyarat

Pastikan sudah terinstall:

  • Python versi 3.10 atau lebih baru
  • pip
  • virtualenv
  • FFmpeg untuk audio/STT
  • Backend Road2Work.id sudah berjalan jika ingin mencoba flow penuh

Cek FFmpeg:

ffmpeg -version

Jika belum tersedia, install FFmpeg terlebih dahulu sesuai sistem operasi yang digunakan.

⚙️ Setup Local

Masuk ke folder machine-learning:

cd machine-learning

Buat virtual environment:

python -m venv .venv

Aktifkan virtual environment.

Windows PowerShell

.venv\Scripts\Activate.ps1

Windows CMD

.venv\Scripts\activate.bat

Linux / macOS

source .venv/bin/activate

Install dependency:

pip install -r requirements.txt

Buat file .env dari .env.example:

cp .env.example .env

Contoh konfigurasi .env local:

OPENAI_API_KEY=isi_openai_api_key
OPENAI_MODEL=gpt-5.4-mini
OPENAI_MAX_OUTPUT_TOKENS=2048
GENAI_MAX_RETRIES=3

ROAD2WORK_DATA_DIR=data

STT_MODEL_SIZE=small
STT_LANGUAGE=id

Jalankan service:

uvicorn main:app --host 127.0.0.1 --port 8000 --reload

Buka dokumentasi API:

http://127.0.0.1:8000/docs

🔐 Environment Variables

Variable Keterangan
OPENAI_API_KEY API key untuk OpenAI Responses API
OPENAI_MODEL Model yang dipakai untuk pertanyaan dan evaluasi
OPENAI_MAX_OUTPUT_TOKENS Batas maksimal output token
GENAI_MAX_RETRIES Jumlah retry jika request AI gagal sementara
ROAD2WORK_DATA_DIR Path folder data Machine Learning
STT_MODEL_SIZE Ukuran model faster-whisper
STT_LANGUAGE Bahasa transkripsi, default id

Contoh local:

ROAD2WORK_DATA_DIR=data

Contoh jika data diarahkan ke folder tertentu:

ROAD2WORK_DATA_DIR=E:\Kuliah\DBS Dicoding\2026\Capstone Project\Code\Final Apps\machine-learning\data

🌐 Endpoint Utama

🩺 Health Check

GET /

Digunakan untuk memastikan service berjalan.

📄 Extract CV

POST /v1/context/extract-cv

Input:

  • Multipart file CV

Output:

  • Professional summary
  • Skills
  • Tools
  • Experience signals
  • Achievements
  • Evidence items

👤 Extract Short Profile

POST /v1/context/extract-short-profile

Input:

  • Profile summary
  • Target role
  • Skill/tools manual

Output:

  • Structured profile context

🎧 Transcribe Audio

POST /v1/stt/transcribe

Input:

  • Audio file

Output:

  • Transcript
  • Confidence / metadata jika tersedia

❓ Generate Question

POST /v1/interview/generate-question

Input:

  • Target role
  • Profile context
  • Interview history
  • Current state
  • Improvement focus

Output:

  • Adaptive question
  • Question type
  • Competency focus

🧪 Evaluate Answer

POST /v1/interview/evaluate-answer

Input:

  • Question
  • Answer transcript
  • Target role
  • Profile context
  • Previous answers

Output:

  • Score breakdown
  • Final score
  • Evidence level
  • Weakness
  • Clarification decision
  • Stronger answer
  • Next recommendation

🎙️ Interview State

Service mendukung flow interview berikut:

IDLE
→ ASKING
→ LISTENING
→ THINKING
→ CLARIFYING / ASKING
→ COMPLETED

Fungsi ML/AI terutama aktif pada state:

THINKING

Pada state ini sistem akan:

  • Memproses transcript
  • Mengevaluasi jawaban
  • Menentukan apakah perlu klarifikasi
  • Menyiapkan pertanyaan berikutnya
  • Menyusun feedback dan result

🪜 Evidence Ladder

Road2Work.id menggunakan konsep Evidence Ladder untuk menilai kekuatan jawaban user saat interview.

Level Nama Contoh
1 Claim “Saya bisa membuat dashboard.”
2 Skill “Saya menggunakan Excel dan Python.”
3 Context “Saya membuat dashboard untuk data penjualan.”
4 Impact “Dashboard membantu tim memahami performa produk.”
5 Measurable Result “Waktu pembuatan laporan berkurang dari 2 jam menjadi 30 menit.”

Semakin tinggi evidence level, semakin kuat jawaban interview user.

📊 Scoring

Evaluasi jawaban menggunakan beberapa dimensi:

  • Role relevance
  • STAR structure
  • Evidence specificity
  • Technical accuracy
  • Communication clarity
  • Self awareness

Bobot penilaian utama:

Dimensi Bobot
Role Relevance 25%
STAR Structure 20%
Evidence Specificity 20%
Technical Accuracy 15%
Communication Clarity 10%
Self Awareness 10%

Final score akan dinormalisasi sebelum dikirim kembali ke backend.

🎧 STT Notes

Speech-to-text menggunakan faster-whisper.

Rekomendasi local:

STT_MODEL_SIZE=small
STT_LANGUAGE=id

Jika transkripsi kurang akurat:

  • Gunakan microphone yang lebih jelas
  • Kurangi noise ruangan
  • Gunakan model STT lebih besar jika resource cukup
  • Pastikan audio dikirim dengan format yang didukung, seperti webm, wav, atau mp3

🧪 Script Testing Manual

Jalankan service:

uvicorn main:app --host 127.0.0.1 --port 8000 --reload

Buka Swagger:

http://127.0.0.1:8000/docs

Tes endpoint berikut:

  • Upload CV ke /v1/context/extract-cv
  • Tes transkripsi audio ke /v1/stt/transcribe
  • Tes generate question ke /v1/interview/generate-question
  • Tes evaluate answer ke /v1/interview/evaluate-answer

🔗 Integrasi Dengan Backend

Backend harus mengarah ke service ini melalui environment variable:

ML_SERVICE_URL=http://localhost:8000

Production:

ML_SERVICE_URL=https://your-ml-service-url

Backend akan meneruskan request dari frontend ke Machine Learning service.

🚢 Deployment Notes

Sebelum deploy, pastikan:

  • .env production sudah tersedia di server
  • OPENAI_API_KEY valid
  • ROAD2WORK_DATA_DIR mengarah ke folder data yang benar
  • FFmpeg tersedia di environment deployment
  • Dependency Python berhasil di-install
  • Service dapat diakses oleh backend

Contoh command production:

uvicorn main:app --host 0.0.0.0 --port 8000

Jika menggunakan process manager atau Docker, pastikan port 8000 terbuka untuk backend service.

🚫 Git Ignore Notes

Jangan commit file berikut:

.env
.venv/
__pycache__/
uploads/
tmp/
temp/
*.wav
*.mp3
*.m4a
*.webm
models/*.keras
models/*.h5
models/*.pb
models/*.savedmodel/

Data kecil yang dibutuhkan service boleh di-commit:

data/

Model besar sebaiknya disimpan di external storage atau Git LFS.

🛠️ Troubleshooting

OPENAI_API_KEY tidak terbaca

Cek file .env:

OPENAI_API_KEY=...

Restart service setelah mengubah .env.

422 Unprocessable Entity

Biasanya payload request tidak sesuai schema endpoint.

Cek Swagger di:

http://127.0.0.1:8000/docs

Pastikan field wajib sudah dikirim.

STT gagal membaca audio

Pastikan:

  • FFmpeg sudah terinstall
  • Format audio didukung
  • File audio tidak kosong
  • Microphone browser benar-benar aktif

Port 8000 sudah dipakai

Cek proses yang memakai port.

Windows PowerShell:

netstat -ano | findstr :8000

Matikan proses:

taskkill /PID <PID> /F

Atau jalankan di port lain:

uvicorn main:app --host 127.0.0.1 --port 8001 --reload

Hasil pertanyaan kurang adaptif

Pastikan request ke /v1/interview/generate-question mengirim context yang lengkap:

  • Target role
  • Profile context
  • Previous answers
  • Improvement focus
  • Previous questions
  • Current interview state

Tanpa context tersebut, pertanyaan akan cenderung generic.

📌 Status MVP

MVP Road2Work.id saat ini berfokus pada domain Information Technology.

Ekspansi domain lain dapat dilakukan dengan menambah taxonomy role, competency map, dan dataset pendukung.

👥 Author

Road2Work.id Capstone Project CC26-PSU050

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages