TalentFlow automates the recruitment interview process using conversational AI avatars. Recruiters create job postings, add candidates, and let an AI conduct personalized voice or video interviews - then review scored results with detailed feedback. Candidates get a natural, face-to-face interview experience powered by a realistic video avatar, with no login required.

For Recruiters:

• Create job postings with custom interview configurations (number of questions, duration, predefined questions)
• Add candidates with resume uploads (PDF, DOC, DOCX) - resumes are automatically parsed and used to personalize each interview
• Send unique interview links to candidates
• Review AI-scored results: technical skills, communication, problem-solving, cultural fit, and an overall letter grade (A+ to F)
• Read AI-generated summaries with strengths, weaknesses, and hiring recommendations

For Candidates:

• Join an interview via a unique link - no account needed
• Choose between a video interview (AI avatar via Tavus) or audio-only mode
• Take up to 2 practice interviews first, with immediate AI coaching feedback and a compatibility report
• Answer questions naturally via microphone; the AI listens, transcribes, and asks intelligent follow-ups based on the job description and resume
• Download a transcript after completion

Recruiter creates job ──► Adds candidate + resume ──► Sends interview link
                                                            │
                                    ┌───────────────────────┘
                                    ▼
                          Candidate opens link
                                    │
                     ┌──────────────┼──────────────┐
                     ▼              ▼              ▼
               Practice Mode   Video Mode    Audio Mode
               (AI coaching)   (Tavus avatar) (Voice only)
                     │              │              │
                     ▼              ▼              ▼
              Compatibility       AI conducts interview
              report (1x)     (questions ─► answers ─► follow ups)
                                    |
                                    │
                                    ▼
                          Auto-scoring + analysis
                          (resume match + interview performance)
                                    │
                                    ▼
                          Recruiter reviews results

The AI avatar appears as a full-screen video call. It greets the candidate by name, asks questions tailored to the job and resume, listens to spoken answers, and moves through the interview at a natural pace. The system uses multiple termination strategies (objectives tracking, prompt-based farewell detection, silence polling) to end the interview cleanly. If Tavus is unavailable, it falls back to audio-only mode automatically.

Each completed interview produces:

• Resume match score (0–100) - how well the resume fits the job
• Interview performance score (0–100) - based on answer quality across all questions
• Combined overall score with letter grade
• Sub-scores for technical skills, communication, problem-solving, and cultural fit
• AI-generated summary, strengths, weaknesses, and hiring recommendation

TalentFlow/
├── apps/
│   ├── accounts/        # Custom User model (recruiter/admin roles)
│   ├── jobs/            # Job posting CRUD + interview config
│   ├── candidates/      # Candidate management, resume parsing, invite tokens
│   ├── interviews/      # Interview engine: AI interviewer, Tavus/HeyGen/D-ID
│   │   ├── services/    #   AIInterviewer, VoiceService, TavusService, etc.
│   │   ├── views.py     #   Audio + video interview endpoints
│   │   └── models.py    #   Interview, InterviewSession, Message
│   ├── results/         # Scoring service, interview analysis, question feedback
│   └── core/            # Shared utilities, management commands
├── templates/           # Django templates (interview UI, dashboards, auth)
├── static/              # CSS, JS (interview logic, avatar engines)
├── talentflow/
│   └── settings/        # Split settings: base / development / production
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── manage.py

• Python 3.11+ (or Docker)
• API keys for: OpenAI or Anthropic, ElevenLabs, Tavus (optional, for video)

git clone https://github.com/Cipherweave/TalentFlow.git
cd TalentFlow

# Configure environment
cp .env.example .env
# Edit .env with your API keys (see Environment Variables below)

# Build and run
docker-compose up -d
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py init_superuser

# Open http://localhost:8000

git clone https://github.com/Cipherweave/TalentFlow.git
cd TalentFlow

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 API keys

python manage.py migrate
python manage.py init_superuser
python manage.py collectstatic --noinput
python manage.py runserver

# Open http://localhost:8000

# Django
SECRET_KEY=your-secret-key
DEBUG=True
DJANGO_SETTINGS_MODULE=talentflow.settings.development

# AI - at least one required
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...       # optional fallback

# Voice - required for audio interviews
ELEVENLABS_API_KEY=...
ELEVENLABS_VOICE_ID=...

# Video avatar - optional, enables video interview mode
TAVUS_API_KEY=...
TAVUS_PERSONA_ID=...
TAVUS_REPLICA_ID=...
INTERVIEW_USE_VIDEO_AVATAR=True    # set False to disable video mode

# Superuser auto-creation
DJANGO_SUPERUSER_USERNAME=admin
DJANGO_SUPERUSER_EMAIL=admin@talentflow.com
DJANGO_SUPERUSER_PASSWORD=admin123

After running init_superuser: admin / admin123 at http://localhost:8000/admin

• Multi-provider avatar strategy: Tavus is the primary video provider, with HeyGen and D-ID as alternatives. The architecture allows swapping providers without changing the interview flow.
• Automatic fallback: If the video avatar service is unavailable, interviews seamlessly fall back to audio-only mode mid-session.
• Practice mode with privacy: Candidates can practice up to 2 times with full AI coaching feedback. Practice results are shown once and not saved to the recruiter's dashboard.
• Robust interview termination: A chain of fallback mechanisms (objectives API, prompt-based farewell, silence detection, manual button) ensures interviews end cleanly without awkward hangs.
• No candidate authentication: Candidates access interviews via unique UUID tokens - no sign-up friction.
• Resume-aware AI: The interviewer receives the full job description and parsed resume, enabling tailored questions and accurate scoring.

Docker:

docker-compose down          # Stop and remove containers
docker-compose down -v       # Also remove database volume (full reset)

Local Python:

# If running in the foreground, stop with Ctrl+C

# If running in the background, find and kill the process:
lsof -i :8000               # Find the process using port 8000
kill <PID>                   # Stop it (use the PID from the output above)

deactivate                   # Exit the virtual environment