Interview Trainer Agent

AICTE-2026 / IBM SkillsBuild

Stack: IBM Cloud Lite · IBM Granite (via watsonx.ai) · RAG (ChromaDB) · FastAPI · WebSocket

An AI-powered mock interview coach that parses your résumé, retrieves role-specific material from a vector knowledge base, conducts a natural conversational interview with live token streaming, evaluates each answer with evidence-based scoring, and produces an end-of-session performance report.

Architecture

User ──► Orchestrator  ──┬──► Profile Parser          (LLM temp 0.1)
                         ├──► Query Formulator ──► ChromaDB (RAG)
                         ├──► Question Generator     (LLM temp 0.65)
                         ├──► Conversationalist ◄──► (multi-turn, streams tokens)
                         ├──► Answer Evaluator        (LLM temp 0.25, dual-call)
                         ├──► Session Summarizer      (LLM temp 0.25)
                         └──► Hint Generator          (on-demand Socratic nudge)

Session state machine

AWAITING_PROFILE → PROFILE_PARSED → QUESTION_READY → INTERVIEWING
    → ANSWER_RECEIVED → FEEDBACK_GIVEN → (loop N questions)
    → SESSION_COMPLETE

Component responsibilities

#	Component	Temperature	Output contract
3.1	Orchestrator	0.1	`{"action": "...", "reasoning": "..."}`
3.2	Profile Parser	0.1	`ParsedProfile` JSON
3.3	Query Formulator	0.1	`{"query": "..."}` for vector store
3.4	Question Generator	0.65	`QuestionRecord` JSON + internal ideal-answer pointers
3.5	Conversationalist	0.75	Plain conversational text (streamed token-by-token)
3.6	Answer Evaluator	0.25	`QuestionEvaluation` with scores & feedback
3.7	Session Summarizer	0.25	`SessionSummary` JSON
—	Hint Generator	0.6	One-sentence Socratic nudge (on-demand)

Project structure

interview_trainer/
├── __init__.py
├── config.py              ← env-var configuration (no hardcoded secrets)
├── models.py              ← Pydantic schemas for all data contracts
├── llm_client.py          ← IBM Granite API wrapper + defensive JSON parsing
├── vector_store.py        ← ChromaDB + sentence-transformers RAG layer
├── session_manager.py     ← State machine, guardrails, streaming generator
├── ingest.py              ← PDF / TXT / MD ingestion (CLI + importable)
├── app.py                 ← FastAPI REST + WebSocket + SSE endpoints
├── cli.py                 ← Interactive terminal interface
└── components/
    ├── orchestrator.py       ← Section 3.1 — routing controller
    ├── profile_parser.py     ← Section 3.2 — résumé → ParsedProfile
    ├── query_formulator.py   ← Section 3.3 — profile → vector-store query
    ├── question_generator.py ← Section 3.4 — context + profile → QuestionRecord
    ├── conversationalist.py  ← Section 3.5 — live interviewer dialogue
    ├── evaluator.py          ← Section 3.6 — answer scoring
    ├── summarizer.py         ← Section 3.7 — session summary
    └── hint_generator.py     ← Socratic mid-answer hints (on-demand)
data/
└── seed_knowledge_base.txt   ← Sample knowledge base (ingest before first run)
tests/
└── test_agent.py             ← 77 unit + integration tests (no real API calls)

Quick start

1. Clone and install

git clone https://github.com/MithunKumarRajak/Interview-trainer-agent.git
cd interview-trainer-agent
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Python version: 3.10 or later required (uses X | Y union syntax and match expressions).

2. Configure credentials

cp .env.example .env

Open .env and fill in your IBM Cloud credentials:

WATSONX_API_KEY=<your IBM Cloud API key>
WATSONX_PROJECT_ID=<your watsonx.ai project ID>
WATSONX_URL=https://us-south.ml.cloud.ibm.com   # adjust region if needed

See Environment variables for the full list of settings.

3. Seed the knowledge base

The RAG layer needs at least a few documents before it can generate grounded questions.

# Ingest the sample corpus that ships with the repo (recommended for first run)
python -m interview_trainer.ingest --file data/seed_knowledge_base.txt

# Add your own documents (PDF, TXT, or MD)
python -m interview_trainer.ingest --file path/to/job_description.pdf
python -m interview_trainer.ingest --dir  path/to/question_bank/

4a. Interactive CLI

python -m interview_trainer.cli                    # mixed questions (default)
python -m interview_trainer.cli --type technical   # technical questions only
python -m interview_trainer.cli --type behavioral  # behavioral questions only
python -m interview_trainer.cli --verbose          # enable debug logging

4b. REST / WebSocket server

uvicorn interview_trainer.app:app --reload --port 8000

Interactive API docs: http://localhost:8000/docs
Frontend UI: http://localhost:8000/ (served from interview_trainer/static/index.html)

Environment variables

All variables are optional except the three IBM credentials when making real API calls.

Variable	Default	Description
`WATSONX_API_KEY`	(required)	IBM Cloud API key
`WATSONX_PROJECT_ID`	(required)	watsonx.ai project ID
`WATSONX_URL`	`https://us-south.ml.cloud.ibm.com`	watsonx.ai regional endpoint
`GRANITE_MODEL_ID`	`ibm/granite-3-3-8b-instruct`	IBM Granite model to use
`CHROMA_DB_PATH`	`./data/chroma_db`	Directory for the ChromaDB persistent store
`CHROMA_COLLECTION`	`interview_knowledge_base`	Collection name inside ChromaDB
`EMBEDDING_MODEL`	`all-MiniLM-L6-v2`	sentence-transformers model for embeddings
`MAX_QUESTIONS_PER_SESSION`	`5`	Questions asked before the session ends
`MAX_FOLLOW_UPS_PER_QUESTION`	`2`	Max follow-up turns per question
`MAX_CLARIFY_RETRIES`	`2`	Off-topic messages before a forced re-engagement reply
`MAX_INJECTION_ATTEMPTS`	`3`	Prompt-injection attempts before the session is suspended
`ADMIN_API_KEY`	(required for `/admin/ingest`)	Bearer token protecting the admin ingest endpoint
`CORS_ORIGINS`	`*`	Comma-separated allowed CORS origins; use `*` for development

REST & WebSocket API reference

Sessions

Method	Path	Request body	Response	Description
`POST`	`/sessions`	`{"question_type": "mixed"}`	`{session_id, message}`	Create a new session. `question_type`: `technical`, `behavioral`, or `mixed`.
`GET`	`/sessions/{id}`	—	`{session_id, state, questions_completed, profile_role, profile_level}`	Inspect current session state.
`DELETE`	`/sessions/{id}`	—	204 No Content	Delete a session and free its memory.

Messaging

Method	Path	Request body	Response	Description
`POST`	`/sessions/{id}/message`	`{"message": "..."}`	`{reply, session_state}`	Send a text message; returns the full reply synchronously.
`POST`	`/sessions/{id}/message/stream`	`{"message": "..."}`	SSE `text/event-stream`	Streaming variant — emits the same JSON event envelope as WebSocket (see below).
`WS`	`/sessions/{id}/live`	`{"message": "...", "resume_text": null}`	JSON text frames	WebSocket live simulation mode — token-by-token streaming.

Resume & hints

Method	Path	Request body	Response	Description
`POST`	`/sessions/{id}/upload-resume`	`multipart/form-data` (`file`, `question_type`)	`{reply, session_state}`	Upload a PDF, TXT, or MD résumé file.
`POST`	`/sessions/{id}/hint`	—	`{hint}`	Request a Socratic mid-answer hint for the current active question.

Analytics

Method	Path	Response	Description
`GET`	`/sessions/{id}/heatmap`	`{dimensions, question_labels}`	Per-dimension score arrays for the confidence heatmap chart.
`GET`	`/sessions/{id}/history`	`{session_id, profile_role, total_questions, questions[]}`	Full question-by-question history with scores and feedback.

Admin

Method	Path	Auth	Response	Description
`GET`	`/health`	—	`{status, vector_store_docs}`	Liveness probe.
`POST`	`/admin/ingest`	Bearer `ADMIN_API_KEY`	`{chunks_ingested, collection_size}`	Ingest a PDF / TXT / MD document into the vector store.

Full session example (curl)

# 1. Create a session
SESSION=$(curl -s -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{"question_type": "mixed"}' \
  | python -c "import sys,json; print(json.load(sys.stdin)['session_id'])")

echo "Session: $SESSION"

# 2. Provide your profile / résumé
curl -s -X POST "http://localhost:8000/sessions/$SESSION/message" \
  -H "Content-Type: application/json" \
  -d '{"message": "I am a mid-level Python backend engineer with 3 years experience in Django and PostgreSQL."}'

# 3. Start the interview
curl -s -X POST "http://localhost:8000/sessions/$SESSION/message" \
  -H "Content-Type: application/json" \
  -d '{"message": "start"}'

# 4. Answer questions (repeat as needed)

# 5. Request the session summary
curl -s -X POST "http://localhost:8000/sessions/$SESSION/message" \
  -H "Content-Type: application/json" \
  -d '{"message": "summary"}'

# 6. View the performance heatmap
curl -s "http://localhost:8000/sessions/$SESSION/heatmap"

# 7. Clean up
curl -s -X DELETE "http://localhost:8000/sessions/$SESSION"

WebSocket live simulation

The WebSocket endpoint (WS /sessions/{id}/live) delivers token-by-token streaming so the interviewer's response appears character-by-character in real time. Both WebSocket and SSE transports emit structurally identical JSON events.

Event envelope

Event	Fields	When emitted
`connected`	`session_id`	WS only — handshake confirmed
`thinking`	—	Pipeline started; disable user input
`ttft`	—	First token imminent; create the streaming bubble
`token`	`delta: str`	Each LLM chunk (conversationalist only)
`done`	`reply: str`, `session_state: str`, `evaluation: obj\|null`	Turn complete; re-enable input
`error`	`message: str`	Pipeline error or invalid session

Quick WebSocket test (Python)

import asyncio, json, websockets

async def live_demo():
    session_id = "<your-session-id>"   # create via POST /sessions first
    uri = f"ws://localhost:8000/sessions/{session_id}/live"
    async with websockets.connect(uri) as ws:
        # Wait for the 'connected' confirmation
        print(json.loads(await ws.recv()))

        # Send a message
        await ws.send(json.dumps({"message": "start", "resume_text": None}))

        # Collect events until 'done'
        while True:
            evt = json.loads(await ws.recv())
            if evt["type"] == "token":
                print(evt["delta"], end="", flush=True)
            elif evt["type"] == "done":
                print("\n--- turn complete ---")
                break

asyncio.run(live_demo())

Running tests

pytest tests/ -v

All 77 tests mock the IBM Granite API — no real credentials required. The suite covers:

Model schemas and Pydantic validation
Every pipeline component with success + fallback paths
Injection guard (8 known attack vectors + 5 legitimate-answer false-positive checks)
Dual-call evaluator averaging and borderline-score detection
Orchestrator routing and off-topic flood protection
Session manager streaming handler (handle_message_stream)
WebSocket endpoint: connect, invalid-session protocol, full turn, disconnect preservation
SSE endpoint: content-type, event shape, evaluation key presence
Admin auth: missing key (503), wrong key (403), correct key (pass)

Design decisions

Why a separate LLM call per component?

Each component has its own system prompt, temperature, and output contract. This makes components independently debuggable — you can unit-test the evaluator in isolation by mocking granite_chat_json, without needing the rest of the pipeline. It also makes the architecture transparent in a project review ("here's the routing logic, here's why evaluation uses a lower temperature than generation").

Why ChromaDB + sentence-transformers?

Both run locally with no external service — ideal for IBM Cloud Lite tier. The embedding model (all-MiniLM-L6-v2, ~80 MB) produces strong semantic similarity for technical and HR text without needing a separate embedding API call.

Guardrails

Off-topic flood protection: after MAX_CLARIFY_RETRIES consecutive clarify routing decisions, the pipeline bypasses the LLM and returns a hardcoded re-engagement message, preventing runaway API spend.
Sparse profile guard: is_profile_too_sparse() counts null fields; if ≥ 2 are missing the pipeline stops and prompts the user for more detail rather than guessing and generating irrelevant questions.
JSON parsing failures: _extract_json() in llm_client.py strips prose wrappers with a regex fallback; granite_chat_json() retries once with a stricter JSON-only reminder, then raises ValueError.
Context window management: only the conversation for the current question (not the full session transcript) is passed to the conversationalist and evaluator. The summarizer receives compact QuestionEvaluation JSON objects, not raw turns.
Injection / jailbreak guard: sanitize_candidate_input() pattern-matches 13 known injection vectors before any LLM call. After MAX_INJECTION_ATTEMPTS flagged messages the session is suspended and transitioned to SESSION_COMPLETE.
Anti-sycophancy evaluator: calibration anchors in the evaluator system prompt prevent the model from inflating scores for confident-sounding but content-free answers. For borderline scores (any dimension in 3–4), a second evaluator call is made and the scores are averaged.

Why in-memory session storage?

The current implementation stores sessions in a plain Python dict for simplicity. For multi-instance or persistent deployments, replace _sessions in session_manager.py with a Redis-backed store. The InterviewSession Pydantic model is fully serialisable (model_dump_json() / model_validate_json()), so the swap is straightforward.

IBM Granite notes

Uses the chat endpoint with separate system and user message roles.
There is no native "JSON mode" — the "Respond with ONLY this JSON" instruction plus _extract_json() defensive parsing is the safety net.
Default model ID: ibm/granite-3-3-8b-instruct (override with GRANITE_MODEL_ID env var).

Troubleshooting

`chromadb` / `sentence-transformers` import errors

pip install --upgrade chromadb sentence-transformers

On Apple Silicon (M-series) you may need:

pip install --upgrade torch --index-url https://download.pytorch.org/whl/cpu

`ibm_watsonx_ai` authentication error (401 / 403)

Verify WATSONX_API_KEY and WATSONX_PROJECT_ID in your .env file.
Ensure your IBM Cloud account has access to the watsonx.ai service and the model ID you configured.
Check that WATSONX_URL matches the region where your project lives (us-south, eu-de, jp-tok, etc.).

Vector store is empty — questions are generic

The agent falls back to general best-practice questions when the vector store returns no results. Run the ingestion step:

python -m interview_trainer.ingest --file data/seed_knowledge_base.txt

WebSocket connection refused / falls back to SSE immediately

Ensure the server is running with uvicorn (not a different ASGI server that may not support WebSocket).
If you're behind a reverse proxy (nginx, Caddy), confirm WebSocket upgrade headers are forwarded (Upgrade: websocket, Connection: Upgrade).
The frontend degrades silently to SSE if the WebSocket handshake fails — check the browser console for [LiveSession] log lines.

`ADMIN_API_KEY not configured` (503 on `/admin/ingest`)

Set the key in .env:

ADMIN_API_KEY=<strong random secret>   # e.g. openssl rand -hex 32

Then pass it as a Bearer token:

curl -X POST http://localhost:8000/admin/ingest \
  -H "Authorization: Bearer <your-key>" \
  -F "file=@path/to/doc.pdf"

Tests fail with `ImportError`

Run tests from the repo root so the package is importable:

cd interview-trainer-agent
pytest tests/ -v

Contributing

Fork the repository and create a feature branch from main.
Install dev dependencies — the project has no separate dev-requirements file; requirements.txt is sufficient.
Run the test suite before pushing:
```
pytest tests/ -v
```
Add tests for any new behaviour — aim for a test per public function and per guardrail path.
Keep commits focused — one logical change per commit, present-tense subject line (e.g. add session expiry TTL, fix evaluator borderline threshold).
Open a pull request against main with a description of what changed and why.

Adding new knowledge-base documents

# Single file
python -m interview_trainer.ingest --file docs/system_design_questions.pdf

# Whole directory
python -m interview_trainer.ingest --dir docs/

The admin REST endpoint can also be used programmatically — see the Admin API reference and the ADMIN_API_KEY troubleshooting note for the Bearer-token curl invocation.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
Problem Statement		Problem Statement
Project presentation-Submission		Project presentation-Submission
data		data
interview_trainer		interview_trainer
tests		tests
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation