Communication Health Analyzer

A sophisticated AI workflow to analyze the "health" of business communications and provide actionable insights for improvement.

🎯 Overview

This project implements an analysis system based on LangGraph and Claude Sonnet 4.5 that evaluates communications across 7 key dimensions:

1. Emotional Tone (20%) - Negative sentiment → Neutral → Positive
2. Clarity (20%) - Ambiguous → Clear and specific
3. Engagement (5%) - Disengaged → Highly participative
4. Respect/Professionalism (20%) - Disrespectful → Highly professional
5. Productivity (15%) - Off-topic → Results-oriented
6. Alignment (15%) - Strong disagreement → Full consensus
7. Response Speed (5%) - Delayed → Timely

🏗️ Architecture

The workflow follows a linear pipeline with conditional branching:

START → Input Validator → [Conditional Routing] → Conversation Preprocessor
→ Multi-Dimensional Analyzer → Critical Moments Detector → Timeline Builder
→ Aggregator & Scorer → Explainer → Output Formatter → END

Main Components

• 8 workflow nodes: 4 with LLM (parsing, analysis, detection, explanation), 4 deterministic
• Multi-Model Strategy: Optimized Claude models for each task (Haiku 4.5, Sonnet 4.5)
• Pydantic v2 Models: Structured output validation
• LangGraph: Workflow orchestration

Multi-Model Strategy

The system uses a multi-model strategy to optimize costs and quality:

Node	Model	Temp	Max Tokens	Rationale
Conversation Preprocessor	Claude Haiku 4.5	0.0	4096	Fast and cost-effective parsing for all conversation types (email, chat, meetings). Temperature 0.0 ensures maximum precision and consistency in structured output extraction. Haiku 4.5 is 40% faster and 50% cheaper than Sonnet while maintaining excellent accuracy for structured parsing tasks.
Dimensional Analyzer	Claude Sonnet 4.5	0.2	8000	High-quality multi-dimensional scoring requiring deep understanding of communication nuances. Temperature 0.2 balances consistency with slight flexibility for edge cases. Increased max_tokens (8000) handles complex output: 7 dimensions × N messages with detailed reasoning per score. Sonnet 4.5's superior reasoning capabilities ensure accurate evaluation across all dimensions.
Critical Moments Detector	Claude Sonnet 4.5	0.3	6000	Pattern detection requiring creative insight to identify tension spikes, breakthroughs, deadlocks, misalignments, and positive turns. Temperature 0.3 allows slight creativity while maintaining reliability. Sonnet 4.5's advanced pattern recognition excels at detecting subtle communication shifts that simpler models might miss.
Explainer	Claude Sonnet 4.5	0.4	6000	Professional-quality text generation for executive summaries, key findings, and actionable recommendations. Temperature 0.4 balances consistency with natural language variety. Sonnet 4.5 produces clear, well-structured explanations that stakeholders can immediately act upon.

📋 Requirements

• Python 3.11+
• ANTHROPIC_API_KEY

🚀 Installation

1. Clone the repository

cd varolio-assignment

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

# For production use
pip install -r requirements.txt

# For development (includes testing and quality tools)
pip install -r requirements-dev.txt

Note: The pyproject.toml file contains only tool configurations (Black, Ruff, Mypy, pytest). Dependencies are managed via requirements.txt files.

4. Configure environment variables

cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

💻 Usage

Running the Analysis

Run the main script:

python main.py

The script will prompt you for the input file path:

Enter file path: examples/email_thread_positive.txt

The analysis results will be:

• Displayed in the terminal with a formatted summary
• Saved as JSON in outputs/output_{timestamp}.json

Supported input formats:

• Email threads (with From: / To: headers)
• Meeting transcripts (with Speaker: dialogue format)
• Chat conversations

With LangGraph Studio

langgraph dev

This will start LangGraph Studio with a visual interface to test the workflow.

📊 Workflow Output

The workflow produces a structured JSON with:

Metadata

• Analysis timestamp
• Participants
• Conversation duration

Macro Analysis

• Overall health score (0-1)
• Category (excellent/good/fair/poor)
• Scores per dimension
• Top 2 strengths
• Top 2 areas for improvement

Micro Analysis

• Critical Moments: Key moments (tension spike, breakthrough, deadlock, etc.)
• Timeline: Communication evolution over time (quartiles)
• Per-Message Scores: Detailed scores for each message

Explanation

• Executive summary (2-3 paragraphs)
• 3-5 key findings
• 2-5 prioritized recommendations with actionable steps
• Positive aspects to maintain
• Observed communication patterns

🧪 Testing

The project includes a comprehensive test suite with 240 tests covering all system components:

• 186 unit tests (77.5%) - Fast, no API calls required
• 54 integration tests (22.5%) - Require ANTHROPIC_API_KEY

Test Suite Overview

• Unit Tests (tests/unit/): Tests for deterministic nodes, config, schemas, state, graph
• Integration Tests (tests/integration/): End-to-end tests, error handling, edge cases, advanced scenarios
• Shared Fixtures (tests/conftest.py): 20+ reusable fixtures for conversations, state, etc.
• Coverage: ~95% overall, 95-100% on critical components

Running Tests

Unit Tests (fast, no API key required)

# All unit tests
pytest tests/unit/ -v

# Specific tests
pytest tests/unit/test_input_validator.py -v
pytest tests/unit/test_prompts.py -v
pytest tests/unit/test_graph.py -v
pytest tests/unit/test_state.py -v

Integration Tests (require ANTHROPIC_API_KEY)

# All integration tests
pytest tests/integration/ -v -m integration

# Specific tests
pytest tests/integration/test_workflow_integration.py -v
pytest tests/integration/test_error_handling.py -v

All Tests

# Run all tests (unit + integration)
pytest tests/ -v

# Run only unit tests (skip integration)
pytest tests/ -v -m "not integration"

Coverage Report

# Generate coverage report
pytest tests/ --cov=src --cov-report=html

# Open HTML report
open htmlcov/index.html  # macOS/Linux
start htmlcov\index.html  # Windows

📁 Project Structure

varolio-assignment/
├── src/
│   ├── config/           # Configuration and constants
│   │   ├── settings.py   # Dimension weights, thresholds, LLM config
│   │   └── logger.py     # Logging setup
│   ├── models/           # Pydantic models and state
│   │   ├── schemas.py    # All Pydantic models
│   │   └── state.py      # WorkflowState TypedDict
│   └── workflow/
│       ├── nodes/        # 8 workflow nodes
│       │   ├── input_validator.py
│       │   ├── conversation_preprocessor.py
│       │   ├── dimensional_analyzer.py
│       │   ├── critical_moments.py
│       │   ├── timeline_builder.py
│       │   ├── aggregator_scorer.py
│       │   ├── explainer.py
│       │   └── output_formatter.py
│       ├── prompts/      # Prompt templates for LLM nodes
│       └── graph.py      # LangGraph orchestration
├── tests/
│   ├── conftest.py      # Shared pytest fixtures (20+ fixtures)
│   ├── unit/            # Unit tests for deterministic nodes (10 files)
│   └── integration/     # Integration tests and edge cases (4 files)
├── examples/
│   └── run_analysis.py  # Example script
├── pyproject.toml       # Dependencies and config
├── langgraph.json       # LangGraph Studio config
└── README.md

⚙️ Advanced Configuration

Modify Dimension Weights

Edit src/config/settings.py:

DIMENSION_WEIGHTS = {
    "emotional_tone": 0.25,  # Increase weight
    "clarity": 0.20,
    # ...
}

Modify LLM Temperatures

TEMPERATURES = {
    "conversation_preprocessor": 0.0,
    "dimensional_analyzer": 0.3,  # Increase creativity
    # ...
}

Modify Category Thresholds

HEALTH_THRESHOLDS = {
    "excellent": 0.85,  # Make more stringent
    "good": 0.70,
    # ...
}

🔍 Handled Edge Cases

1. Input too short: Validation with minimum length
2. Insufficient messages: Minimum 2 messages required
3. Missing timestamps: Sequential creation with flag
4. Multilingual content: Processed by Claude (native support)
5. Single participant: Neutral scores for non-applicable dimensions

📚 Main Dependencies

• langgraph>=0.2.0 - Workflow orchestration
• langchain-anthropic>=0.2.0 - Claude integration
• pydantic>=2.0.0 - Data validation
• python-dotenv>=1.0.0 - Environment variable management