voice

Voice — Voice Elicitation Interview Engine

Voice is an adaptive voice elicitation interview engine that builds a comprehensive written-voice profile through a structured conversational interview. The engine administers 60-80 questions across 12 thematic modules, adapting its path based on the participant's responses and detected writer type.

Architecture Overview

• Question Bank: JSON question files organized by module in question-bank/modules/, validated against question-bank/schemas/question.schema.json
• Branching Logic: Conditional paths in question-bank/branching/ that route participants through writer-type-specific question sequences
• NLP Pipeline: Text analysis stages in nlp/ that extract stylistic signals from open-ended and writing-sample responses
• Scoring Engine: Dimension scoring in scoring/ that maps responses to voice profile dimensions with weighted aggregation
• Agents: Specialized conductor and analyst agents in agents/ that orchestrate the interview flow

Interview Modules

The interview spans 12 modules plus a screening/demographic preamble (SD). Modules cover dimensions such as formality and register, emotional tone, sentence structure, vocabulary preferences, rhetorical patterns, audience awareness, and stylistic identity. Each module contains 4-8 questions with a mix of question types (likert, forced_choice, scenario, open_ended, writing_sample, calibration, etc.) to triangulate self-reported preferences against observed behavior.

Starting an Interview

1. Generate a UUID session ID.
2. Create the session directory at ~/.human-voice/sessions/{session_id}/.
3. Initialize state.json with status init, empty response arrays, and module progress tracking.
4. Load the question bank from the project's question-bank/modules/ directory.
5. Begin with the screening/demographic module (SD) to establish baseline writer type and branching path.
6. Progress through modules in sequence, applying branching rules and format rotation to maintain engagement.