Bin-H-17/research-mock-interview

Research Mock Interview Hermes Skill

1. What is This

A local-first research scenario mock interview system, delivered as a Hermes Skill. It reads the candidate's real research materials (CV / Projects / Papers) and uses a pluggable LLM backend to act as a strict examiner for scenarios like graduate school applications (保研/申博), research job interviews, thesis defenses, group meetings, and overseas PhD interviews. It conducts multi-turn conversational mock interviews and issues hard-blocking follow-ups when answers are too shallow. After the session, it produces a score, a weakness library, and a review report.

1.1 Consistency with Architecture (Decisions Locked)

• X1 Target Users: All directions (保研/申博 + lightweight job interview). v1 covers six scenario types: 保研/申博/求职/答辩/组会/海外PhD.
• X2 Form: Local Hermes Skill + public content引流; this repo is the Skill itself.
• X3 Voice: v1.1 implements 'pluggable voice duplex' – mock runs the entire pipeline offline with zero dependencies; real STT (vosk/whisper) and real TTS (pyttsx3/edge-tts) are optional backends, all lazy-loaded, with clear runtime errors on missing dependencies (does not break core zero-dependency).
• X4 WeChat Collection: Abandoned – this Skill does not collect any external content sources.
• X5 Python Version: Target 3.12, minimum 3.11 (see requirements.txt and §6).
• Pluggable LLM Backend: Abstract interface + mock (offline, zero dependencies) / ollama (local default) / cloud (BYOK, keys never persisted to disk).
• Cold-Start Materials: Anonymized sample data ships first (data/sample_profile.json), with a real data import entry point (cli run --profile).
• Privacy Iron Law: Local single-tenant, deletable, no telemetry, no outbound; tenant_id=local; purge one-key clears all owner data.

2. When to Trigger

• The user wants to practice / review a research interview (保研, 申博, research job, defense, group meeting, overseas PhD).
• The user wants a stress test that forces them to 'explain clearly and in detail' based on their project experience.
• The user needs a structured review report and a list of weaknesses that can be tracked over time.

3. Workflow (Conductor / User Execution Order)

Step 1: Environment Setup (One-Time)

cd research-mock-interview
python --version            # Needs >=3.11, recommended 3.12
pip install -r requirements.txt   # Optional: PyYAML only needed if using config.yaml

Step 2: Run the Demo (Works Offline)

python src/cli.py run --demo

--demo uses built-in sample data + the mock backend and automatically runs the full cycle of 'question → answer → hard-blocking follow-up → scoring → review report', proving the system runs offline and data is persisted to local SQLite.

Step 3: Load Real Data

Organize your real CV/projects into a JSON file (refer to data/sample_profile.json fields), then:

python src/cli.py run --profile /path/to/your_profile.json --scenario 保研

Enter interactive mode and answer each round; type /finish to end and generate a report, /quit to exit early (session still saved).

Step 4: Switch LLM Backend (Optional)

Copy config.example.yaml to config.yaml, change llm.backend to:

• mock: offline zero dependencies (default, good for demos / no network).
• ollama: local default production backend, fill in base_url / model (e.g., qwen2.5:7b).
• cloud: cloud API (BYOK), keys from env vars only (e.g., RMI_LLM_API_KEY), never hardcoded or persisted.

Step 5: View Stored Data and Deletion Rights

python src/cli.py list          # List all interviews for this tenant
python src/cli.py report --id <session_id first 8 chars or full>   # View review report
python src/cli.py weakness      # View weakness library
python src/cli.py purge --yes   # Owner deletion right: clear all local data for this tenant

Step 6 (v1.1 New): Voice Duplex Mode (Pluggable)

# Offline self-check: mock duplex, no microphone/network needed, proves voice orchestration pipeline works end-to-end
python src/cli.py run --demo --voice

# Connect real voice (pip install corresponding optional dependencies first - see requirements.txt)
# Copy config.example.yaml to config.yaml, set voice.enabled=true or add --voice at runtime,
# and change voice.stt/tts backend to vosk/whisper/pyttsx3/edge, fill in model paths.

Step 7 (v1.1 New): Cross-Session Weakness Aggregation

python src/cli.py analyze                 # Aggregate across all scenarios
python src/cli.py analyze --scenario 保研   # View only a specific scenario
python src/cli.py analyze --out report.md  # Export Markdown report

Aggregation dimensions: category distribution, severity distribution, cross-session trends (improved/worsened/stable), recurring weaknesses (≥2 times) with action suggestions.

4. Module Responsibilities (src/)

• llm_backend.py: LLMBackend abstract + MockBackend / OllamaBackend / CloudBackend, from_config(cfg) factory switches based on config.
• storage.py: Store wraps local SQLite persistence with tenant scope isolation, purge_owner() implements deletion rights.
• interview_engine.py: InterviewSession drives 'import → question → hard-blocking follow-up → scoring → weakness library → review report'.
• voice_io.py (v1.1): STTProvider / TTSProvider / DuplexVoice pluggable voice; mock offline zero dependencies, real backends lazy-loaded + missing dependency guard.
• analytics.py (v1.1): aggregate_weaknesses / render_aggregate_report cross-session weakness aggregation (pure standard library).
• cli.py: argparse entry point (run / list / report / weakness / purge / analyze, run supports --voice).

5. Design Constraints (Not to Be Violated)

1. No data egress: All data remains in local SQLite; the cloud backend only sends interview text to the user-configured API, keys from env vars only.
2. No telemetry: No usage data is collected or reported.
3. Deletable: data_dir can be deleted entirely; purge provides programmatic one-click cleanup.
4. Pluggable backends: Business code depends only on the LLMBackend abstraction; adding a new backend only requires implementing generate().
5. Cold-start friendly: Sample data ensures it works out of the box; real data imported via --profile, format backward compatible.

6. Runtime Environment

• Target Python 3.12; minimum 3.11 (see requirements.txt comments).
• Core dependencies: standard library only; PyYAML is optional (only needed when using config.yaml).
• Voice is an optional enhancement: core still has zero hard third-party dependencies; real STT/TTS dependencies are only required when voice is enabled and a real engine is selected (see requirements.txt comments).