Skip to main content

​
Overview

The AIClient class is the main interface for AI-powered interview operations. It handles question generation and feedback analysis by coordinating with AI providers through the provider manager.

​
Initialization

from client.ai_client import AIClient
from client.ai_provider_manager import ProviderManager

# Initialize with a provider manager
client = AIClient(provider_manager=provider_manager)
​
provider_manager
ProviderManager
required
Provider manager instance that handles AI provider coordination and failover

​
Methods

​
generate_first_question()

Generates the opening interview question based on the candidate’s CV and job details. 
question = client.generate_first_question(
    cv_text="5+ years Python development experience...",
    job_desc="Looking for senior backend engineer...",
    job_title="Senior Backend Engineer",
    company_name="TechCorp"
)
​
cv_text
str
required
The candidate’s CV/resume text content
​
job_desc
str
required
The job description text
​
job_title
str
required
The position title being interviewed for
​
company_name
str
required
The hiring company name
​
return
str
A clean, professional opening interview question without prefixes or formatting
Implementation Details:
  • Uses PromptTemplates.first_question_generation() to create the prompt
  • Strips common prefixes like “Question:” or “Here’s a question:”
  • Raises AIServiceError if the response is empty
  • Located at: client/ai_client.py:17

​
generate_followup_question()

Generates follow-up questions based on conversation history and context. 
convo_history = [
    {"role": "assistant", "content": "Tell me about your Python experience"},
    {"role": "user", "content": "I've worked with Python for 5 years..."}
]

question = client.generate_followup_question(
    convo_history=convo_history,
    cv_text=cv_text,
    job_desc=job_desc,
    question_count=1,
    max_questions=8
)
​
convo_history
list[dict]
required
List of conversation messages with role and content keys
​
cv_text
str
required
The candidate’s CV text for context
​
job_desc
str
required
The job description for context
​
question_count
int
required
Current number of questions asked so far
​
max_questions
int
default:"8"
Maximum number of questions in the interview
​
return
str
A contextual follow-up question that builds on the conversation
Implementation Details:
  • Formats conversation history using PromptTemplates.format_conversation_history()
  • Strips prefixes like “Question:”, “Follow-up:”, or “Here’s a question:”
  • Raises AIServiceError if the response is empty
  • Located at: client/ai_client.py:37

​
generate_feedback()

Analyzes the complete interview and returns structured performance feedback. 
feedback = client.generate_feedback(
    convo_history=convo_history,
    cv_text=cv_text,
    job_desc=job_desc,
    job_title="Senior Backend Engineer"
)

print(f"Score: {feedback['score']}/10")
print(f"Strengths: {feedback['strengths']}")
​
convo_history
list[dict]
required
Complete conversation history with all questions and answers
​
cv_text
str
required
The candidate’s CV text
​
job_desc
str
required
The job description
​
job_title
str
required
The position title
​
return
dict
Structured feedback object with the following fields:
​
score
int
Overall performance score from 1 to 10
​
strengths
str
Detailed analysis of candidate’s strong points
​
weaknesses
str
Areas where the candidate could improve
​
cv_improvements
str
Specific suggestions for CV improvements tailored to the role
Implementation Details:
  • Parses JSON response with retry logic (3 attempts with exponential backoff)
  • Validates required keys: score, strengths, weaknesses, cv_improvements
  • Validates score is an integer between 1 and 10
  • Raises AIServiceError for missing keys or invalid score
  • Located at: client/ai_client.py:59

​
Error Handling

All methods may raise AIServiceError in the following cases:
  • Empty AI responses
  • Invalid JSON in feedback generation
  • Missing required feedback fields
  • Invalid score values
  • Provider failures
from app.exceptions import AIServiceError

try:
    question = client.generate_first_question(...)
except AIServiceError as e:
    print(f"AI generation failed: {e}")

​
Internal Methods

​
_generate()

Internal helper that calls provider_manager.generate_text() and wraps exceptions.

​
_parse_json()

Internal JSON parser with retry logic:
  • 3 retry attempts with exponential backoff (2-10 seconds)
  • Strips markdown code block markers
  • Validates JSON structure type (object or array)
  • Located at: client/ai_client.py:86

Build docs developers (and LLMs) love

Get started for freeTalk to us