Interview AI

AI-powered interview automation with LangGraph. Conduct, evaluate, and report on technical interviews with customizable rules and tools.

• Documentation: https://toonformatter.net/docs.html?package=interview-ai
• Source Code: https://github.com/ankitpal181/interview-ai
• Bug Reports: https://github.com/ankitpal181/interview-ai/issues

Installation

pip install interview-ai

Agent Setup (Required)

After installation, run the setup command to initialize the agent configuration:

init-agent

This creates an interview_ai/ directory with:

• config.json - LLM and storage settings
• interview_rules.json - Interview formats and rules
• tools.py - Custom tools for the agent
• .example-env - Environment variables template

⚠️ Important: The package will fail without running init-agent first.

Configuration

Environment Variables

Copy .example-env to .env and configure:

# Required: Choose one (Or leave both blank for Local Models)
OPENAI_API_KEY="your-openai-key"
GOOGLE_API_KEY="your-google-key"

# Optional: Database persistence
POSTGRES_CONNECTION_URI="postgresql://..."
MONGODB_CONNECTION_URI="mongodb://..."

# Optional: Search (Bing)
# BING_SUBSCRIPTION_KEY="your-bing-key"
# BING_SEARCH_URL="https://api.bing.microsoft.com/v7.0/search"

# Optional: LangSmith Tracing
# LANGCHAIN_API_KEY="your-langchain-key"
# LANGCHAIN_TRACING_V2="true"

Config File (interview_ai/config.json)

{
  "llm_model_name": "gpt-4.1-mini",
  "storage_mode": "memory",
  "database_name": "sqlite",
  "internet_search": "duckduckgo"
}

Note: For local models, set llm_model_name to a Hugging Face model name (e.g., meta-llama/Llama-2-7b-chat-hf). The agent will handle downloading and setting it up locally (ensure API keys are blank in .env).

Token Optimization (New)

Interview AI now integrates TOON (Token-Optimized Object Notation) to significantly reduce token usage and cost for LLM calls.

• What it does: Automatically converts JSON data in prompts to the TOON format, which is more concise and token-efficient.
• Benefits: Reduces API costs and latency, especially for long interview contexts.
• Usage: Enable it in your interview_ai/config.json:

{
  "use_toon_formatting": true
}

Quick Start

from interview_ai.clients import InterviewClient

# Initialize with interview format
client = InterviewClient(interview_format="short")

# Start interview
result = client.start()
interview_config = result["interview_config"]
print(result["message"])  # "Please enter your full name"

# Continue interview with user responses
response = client.next(interview_config, user_message="John Doe")
print(response["message"])  # Next question or prompt

# End interview and get evaluation
result = client.end(interview_config)
print(result["evaluation"])  # Final evaluation from LLM

# With operations_map for additional actions
result = client.end(interview_config, operations_map=[
    {
        "type": "email", 
        "receiver_name": "HR Manager", 
        "receiver_relation_to_interview": "Hiring Manager",
        "template": "Here is the candidate report..."
    },
    {
        "type": "whatsapp",
        "receiver_name": "HR Manager",
        "receiver_relation_to_interview": "Hiring Manager",
        "template": "Here is the candidate report..."
    },
    {
        "type": "api", 
        "endpoint": "https://api.company.com/report",
        "body": {"candidate": "John", "rating": "#Description# Extract rating #Description#"},
        "attachment": "#Evaluation PDF#"
    }
])
# Returns: {"evaluation": "...", "email": "...", "whatsapp": "...", "api": "..."}
# Note: Generated files (PDF/CSV) are saved in the 'interview_ai/' directory.

Interview Formats

Pre-configured formats in interview_rules.json:

Format	Questions	Time/Question	Type
short	5	1 min	Mixed
long	5	10 min	Mixed
coding	1	30 min	Coding

Custom Tools

Add your own tools in interview_ai/tools.py:

from langchain_core.tools import StructuredTool

def company_lookup(company_name: str) -> str:
    """Look up company interview patterns."""
    return f"Interview patterns for {company_name}..."

company_tool = StructuredTool.from_function(
    company_lookup,
    description="Look up typical interview questions for a company"
)

# Register your tools here
user_tools = [company_tool]

The agent will automatically load and use your custom tools.

Why Interview AI?

Feature	Interview AI	DIY Agent
Setup Time	5 minutes	Hours/Days
Interview Flow	Built-in graph with phases	Manual state management
Custom Rules	JSON configuration	Hardcoded logic
Custom Tools	Drop-in tools.py	Complex integration
Evaluation	Structured output schema	Custom parsing
Persistence	SQLite/Postgres/MongoDB	Manual implementation
Answer Timer	Automatic expiry	Not included

Robustness & Retries

The agent is built for resilience with built-in retry policies spanning the entire interview lifecycle.

• Automatic Retries: Critical graph nodes (perception, answer collection, reporting) attempt execution up to 3 times on failure.
• Handling Transients: Network blips or temporary LLM API errors are handled gracefully without crashing the interview state.
• Persistence: When combined with a database (Postgres/MongoDB), the agent can recover from hard crashes by resuming from the last successful checkpoint.

This ensures that long-running interviews or batched reporting operations are not lost due to minor sporadic errors.

Documentation

For detailed usage, API reference, and advanced configuration:

📖 Full Documentation

License

MIT © 2025 Ankit Pal