Murphy

A semi-structured LLM interview platform with multi-provider support, real-time voice interaction, and adversarial protection.

Murphy conducts research interviews using configurable question flows with AI-generated follow-ups. Interviews are defined in YAML, follow-up questions are generated in one of four styles (exploratory, deep-dive, clarifying, challenging), and all responses are persisted with full conversation logs.

Features

• Multi-provider LLM support — OpenAI, Ollama, and Anthropic Claude, swappable per session
• Semi-structured interviews — YAML-defined question flows with configurable follow-up counts and styles
• Adaptive follow-ups — LLM-generated follow-up questions with parsing, validation, and fallback logic
• 5-layer security — System prompt hardening, regex pattern detection, optional LLM classification, output validation, and conversation boundary enforcement
• Real-time WebSocket support — Streaming follow-up generation with partial updates
• Voice pipeline (in progress) — STT/TTS with quick-answer sentence splitting and ML-based turn detection
• SvelteKit frontend — Text-mode interview UI with progress tracking

Quick Start

Prerequisites

• Python 3.11+
• uv (Python package manager)
• Node.js 18+ (for the frontend)
• An OpenAI API key, Anthropic API key, or running Ollama instance

Backend

cd backend

# Install dependencies
uv sync --extra dev

# Configure environment
cp .env.example .env
# Edit .env with your API keys and preferences

# Start the server
uv run uvicorn murphy.app:create_app --factory --host 0.0.0.0 --port 8000 --reload

Frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173 to start an interview.

Docker

# Copy and edit the backend env file first
cp backend/.env.example backend/.env

docker-compose up --build

Interview Configuration

Interviews are defined in YAML files placed in backend/interviews/. They are automatically discovered on server startup.

interview:
  title: "Technology & Democracy Interview"
  description: "Understanding perspectives on technology's impact"
  max_duration_minutes: 60
  persona:
    name: "Dr. Sarah Chen"
    role: "Research interviewer"
    tone: "warm, professional, curious"
  introduction: |
    Thank you for participating in this interview...
  questions:
    - id: "tech_emotions"
      text: "How do you feel when using social media?"
      follow_up_count: 2
      follow_up_style: "exploratory"    # exploratory | deep_dive | clarifying | challenging
      context: "Understanding emotional relationship"
      required: true
      transition: "I'd like to shift to..."

Follow-Up Styles

Style	Behavior
exploratory	Broadens the conversation, explores new angles
deep_dive	Asks for specific details, examples, and concrete evidence
clarifying	Seeks to understand ambiguous or unclear points
challenging	Respectfully tests assumptions and reasoning

Environment Variables

Variable	Default	Description
MURPHY_LLM_PROVIDER	openai	LLM backend: openai, ollama, or claude
MURPHY_LLM_MODEL	gpt-4o-mini	Model identifier
OPENAI_API_KEY		Required for OpenAI provider
ANTHROPIC_API_KEY		Required for Claude provider
OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
MURPHY_DATABASE_URL	sqlite+aiosqlite:///./murphy.db	Database connection string
MURPHY_SECURITY_LLM_CLASSIFICATION	false	Enable LLM-based input classification
MURPHY_LOG_LEVEL	INFO	Logging level

API Overview

REST Endpoints

Method	Path	Description
GET	/api/configs	List interview configurations
GET	/api/configs/{id}/questions	Get questions for a config
POST	/api/interviews/sessions	Create a new session
POST	/api/interviews/sessions/{id}/start	Start and get first question
POST	/api/interviews/sessions/{id}/respond	Submit a response
GET	/api/interviews/sessions/{id}/status	Get session progress
GET	/api/interviews/sessions/{id}/responses	Get all responses
POST	/api/interviews/sessions/{id}/terminate	End session
GET	/health	Health check

WebSocket

Connect to /ws/{session_id} for real-time interaction with streaming follow-up generation.

Project Structure

murphyv2/
  backend/
    murphy/
      app.py                  # FastAPI app factory
      config.py               # Pydantic settings
      db.py                   # SQLAlchemy async engine
      models/                 # DB models, API schemas, YAML config models
      core/
        engine.py             # Interview state machine
        orchestrator.py       # Wires engine + LLM + security
        follow_up.py          # Prompt templates + parse/validate
        state.py              # Session state + dataclasses
      providers/
        base.py               # ABCs: BaseLLM, BaseSTT, BaseTTS
        llm/                  # OpenAI, Ollama, Claude providers
      security/               # Pattern detection, classification, output validation
      voice/                  # Voice pipeline stubs (Phase 2)
      api/                    # REST routes + WebSocket handler
    interviews/examples/      # Sample YAML configs
    tests/
  frontend/
    src/
      lib/
        stores/               # Svelte state stores
        components/           # UI components
        services/             # API + WebSocket clients
      routes/                 # SvelteKit pages
    static/worklets/          # AudioWorklet processors

Development

cd backend

# Run tests
uv run pytest tests/ -v

# Run a single test
uv run pytest tests/test_engine.py::TestProcessResponse -v

# Lint
uv run ruff check murphy/ tests/

# Format
uv run ruff format murphy/ tests/

Roadmap

• Phase 1 — Foundation: engine, orchestrator, multi-provider LLM, security, REST API, SvelteKit frontend (text mode)
• Phase 2 — Voice pipeline: STT (Whisper), TTS (Kokoro/Coqui/Orpheus), turn detection, quick/final answer split, interruption handling
• Phase 3 — Additional providers, full LLM-based input classification, OpenAI TTS
• Phase 4 — Admin UI, Twilio integration, session pause/resume, Docker production config

License

MIT License. See LICENSE for details.