OpenAI Tone Analysis

This document explains the OpenAI-based tone analysis feature for journal entries.

Overview

The tone analysis feature automatically detects the emotional tone and sentiment of journal entries using OpenAI's GPT models. This replaces the previous IBM Watson integration with a more flexible and cost-effective solution.

How It Works

Automatic Detection

When creating or updating a journal entry:

1. If no mood is explicitly provided, the system automatically analyzes the entry content
2. Uses OpenAI GPT-4o-mini to analyze tone and sentiment
3. Extracts the primary tone (e.g., "joyful", "sad", "anxious", "calm")
4. Only sets the mood if confidence is above 0.5

Manual Analysis

You can also manually analyze tone via the API endpoint:

POST /api/ai/analyze-tone
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Your journal entry content here...",
  "title": "Optional title"
}

Response:

{
  "primaryTone": "joyful",
  "tones": [
    { "tone": "joyful", "score": 0.85 },
    { "tone": "grateful", "score": 0.72 },
    { "tone": "hopeful", "score": 0.45 }
  ],
  "sentiment": "positive",
  "confidence": 0.87
}

Detected Tones

The system can detect various emotional tones including:

• Positive: joyful, grateful, excited, hopeful, content, peaceful, optimistic
• Negative: sad, anxious, frustrated, angry, worried, disappointed, melancholic, pessimistic
• Neutral: calm, contemplative, neutral, tired

Configuration

Environment Variables

Required:

• OPENAI_API_KEY - Your OpenAI API key

Cost Considerations

• Uses gpt-4o-mini model for cost efficiency
• Only analyzes when mood is not explicitly provided
• Analysis is skipped if OpenAI API key is not configured
• Typical cost: ~$0.0001-0.0003 per analysis

Integration Points

Journal Entry Creation

When creating a new entry via POST /api/journal:

• If mood is provided, it's used as-is
• If mood is not provided, tone analysis runs automatically
• The detected mood is stored in the mood field

Journal Entry Update

When updating an entry via PUT /api/journal/:id:

• If mood is explicitly set, it's used
• If content changes but mood is not set, tone analysis runs
• If content doesn't change, mood is not re-analyzed

Error Handling

• Tone analysis failures are silent (logged but don't block entry creation)
• If analysis fails, mood remains null
• System continues to work normally even if OpenAI is unavailable

Comparison with IBM Watson

Future Enhancements

• User preference to enable/disable auto-detection
• Custom tone categories per user
• Tone history/trends over time
• Batch analysis for existing entries