WellNest - AI-Powered Distributed Assistant

WellNest is a team project implementing a two-node Akka Cluster that provides AI-powered support for mental wellness and academic productivity. The system demonstrates all three Akka messaging patterns (tell, ask, forward) using OpenAI's GPT-4.1-nano model.

Project Overview

The WellNest cluster consists of two specialized nodes:

• Mental Wellness Node (port 2551) - Provides emotional well-being assistance
• Academic Productivity Node (port 2552) - Offers productivity-related support

Each node runs independently but communicates as part of the same Akka Cluster, with intelligent message routing between nodes based on query intent.

Architecture

Cluster Roles

Wellness Node (wellness-node)

• MoodTrackerActor - Tracks user emotional states and provides mood-based responses
• JournalingActor - Generates personalized journaling prompts using LLM
• MindfulnessActor - Provides breathing exercises and mindfulness guidance

Productivity Node (productivity-node)

• PlannerActor - Creates study plans and revision schedules using LLM
• DeadlineActor - Manages mock deadlines and provides preparation advice
• StudyTipActor - Offers study methods and academic strategies

Common Actors (on both nodes)

RouterActor

• Receives all user queries for that node
• Detects intent using keyword matching
• Routes locally if the query belongs to the same node
• Uses forward to send queries to the other node while preserving original sender
• Uses tell to log all incoming and outgoing messages

LLMActor

• Handles all OpenAI API calls
• Supports both live mode (with API key) and mock mode (without internet)
• Only communicates via ask - domain actors send requests and wait for responses

LoggerActor

• Receives tell messages from any actor to log events
• Logs indicate which node processed the request and communication patterns

Messaging Patterns Demonstration

1. Tell (Fire-and-Forget)

• RouterActor → LoggerActor for every message
• MoodTrackerActor → LoggerActor for mood updates
• All actors → LoggerActor for event logging

2. Ask (Request/Response)

• JournalingActor → LLMActor for prompt generation
• PlannerActor → LLMActor for study plan creation
• MindfulnessActor → LLMActor for personalized guidance
• StudyTipActor → LLMActor for academic advice

3. Forward (Preserve Original Sender)

• RouterActor (wellness) → RouterActor (productivity) when productivity query is detected
• RouterActor (productivity) → RouterActor (wellness) when wellness query is detected
• Original sender is preserved so responses route back correctly

Project Structure

src/main/java/com/wellnest/
├── cli/
│   └── TerminalApp.java           # Interactive command-line interface
├── cluster/
│   ├── WellnessNodeMain.java      # Wellness node startup
│   └── ProductivityNodeMain.java  # Productivity node startup
├── common/
│   ├── actors/
│   │   ├── LoggerActor.java       # Logging (tell pattern)
│   │   └── RouterActor.java       # Routing and forwarding
│   └── messages/
│       ├── CborSerializable.java  # Serialization marker
│       ├── UserQuery.java         # Main query message
│       └── LogMessage.java        # Log message
├── llm/
│   ├── actors/
│   │   └── LLMActor.java          # OpenAI integration (ask pattern)
│   ├── messages/
│   │   ├── LLMRequest.java        # LLM request message
│   │   └── LLMResponse.java       # LLM response message
│   └── service/
│       └── OpenAIService.java     # OpenAI API client
├── wellness/
│   └── actors/
│       ├── MoodTrackerActor.java  # Mood tracking
│       ├── JournalingActor.java   # Journaling prompts
│       └── MindfulnessActor.java  # Mindfulness exercises
└── productivity/
    └── actors/
        ├── PlannerActor.java      # Study planning
        ├── DeadlineActor.java     # Deadline management
        └── StudyTipActor.java     # Study tips and advice

Getting Started

Prerequisites

• Java 17 or higher
• Gradle 8.0 or higher
• OpenAI API key (optional - system works in mock mode without it)

Setup

1. Clone and build the project:

   git clone <repository-url>
   cd project-copilot
   gradle build

2. Set OpenAI API key (automatic from .env file): The project includes a .env file with your API key already configured. No manual setup needed!

   Alternative methods:

   # Windows PowerShell (if you want to override .env)
   $env:OPENAI_API_KEY="your-api-key-here"
   
   # Linux/Mac (if you want to override .env)
   export OPENAI_API_KEY="your-api-key-here"

3. Start the cluster nodes:

   Terminal 1 - Wellness Node:

   gradle runWellnessNode

   Terminal 2 - Productivity Node:

   gradle runProductivityNode

4. Start the terminal application:

   Terminal 3 - Client:

   gradle runTerminalApp

Usage Examples

Wellness Queries (Processed by wellness-node:2551)

WellNest> I feel stressed about exams
🧘‍♀️ Wellness Support (from wellness-node:2551)

I understand you're feeling stressed. Here's a quick breathing exercise:
1. Breathe in for 4 counts
2. Hold for 4 counts  
3. Breathe out for 6 counts
4. Repeat 3 times

Would you like me to suggest some mindfulness techniques?

WellNest> I need a journaling prompt
✍️ Journaling Prompt (from wellness-node:2551)

Here's a thoughtful prompt for you:
"What three things challenged you today, and how did you grow from each experience?"
Take 10-15 minutes to write freely.

Productivity Queries (Processed by productivity-node:2552)

WellNest> Give me a 3-day revision plan for algorithms
📚 Study Plan (from productivity-node:2552)

3-Day Algorithm Revision Plan:

Day 1: Foundation Review
• Review basic sorting algorithms (30 min)
• Practice Big O notation problems (45 min)
• Implement bubble sort & merge sort (60 min)

Day 2: Advanced Concepts
• Study graph algorithms (45 min)
• Practice tree traversals (30 min)
• Solve 3-4 leetcode problems (90 min)

Day 3: Final Practice
• Mock exam questions (60 min)
• Review weak areas (30 min)
• Light practice, focus on understanding (45 min)

WellNest> Show me my upcoming deadlines
🗓️ Upcoming Deadlines (from productivity-node:2552)

🔴 Calculus Problem Set 7 - Due in 3 days (High Priority)
🟡 Physics Lab Report - Due in 5 days (Medium Priority)
🟢 History Research Paper - Due in 7 days (High Priority)
⚪ Computer Science Midterm - Due in 10 days (High Priority)

💡 Tip: Start with the calculus problem set since it's due soonest!

Cross-Node Communication (Forward Pattern)

When a wellness query is sent to the productivity node (or vice versa), the system automatically forwards it:

WellNest> I feel anxious about my study schedule
[wellness-node] RouterActor forwarded query from productivity-node
[wellness-node] MoodTrackerActor processing: anxious + study
[Response combines wellness support with study planning advice]

LLM Integration

Live Mode (with API key)

• Calls OpenAI GPT-4.1-nano API
• API key automatically loaded from .env file
• Generates personalized, context-aware responses
• Handles API errors gracefully

Mock Mode (without API key)

• Uses intelligent keyword-based responses
• Maintains full functionality for development/demo
• Clearly indicates when running in mock mode

Logging and Monitoring

All actors use the LoggerActor to track:

• Message routing decisions
• Cross-node communications (forward pattern)
• LLM API calls and responses
• Actor lifecycle events

Example log output:

[INFO] RouterActor@wellness-node: Received query: "I feel stressed"
[INFO] RouterActor@wellness-node: Routed locally to wellness domain
[INFO] MoodTrackerActor@wellness-node: Mood updated for user123: null -> stressed

Key Features Demonstrated

✅ Two-node Akka Cluster with distinct roles
✅ All three messaging patterns: tell, ask, forward
✅ OpenAI GPT-4.1-nano integration with fallback mock mode
✅ Intelligent query routing based on keyword detection
✅ Cross-node communication preserving original sender
✅ Comprehensive logging of all interactions
✅ Domain separation - wellness vs productivity actors
✅ Interactive terminal interface for user queries
✅ Mock data for deadlines and academic scenarios

Development Notes

• Serialization: Uses Jackson CBOR for message serialization
• Configuration: Separate config files for each node type
• Error Handling: Graceful degradation when services are unavailable
• Extensibility: Easy to add new domain actors and capabilities
• Testing: Mock mode enables development without external dependencies

Team Collaboration

This project demonstrates distributed system concepts suitable for a two-person team:

• Person 1: Wellness domain (MoodTracker, Journaling, Mindfulness)
• Person 2: Productivity domain (Planner, Deadlines, StudyTips)
• Shared: Common infrastructure (Router, Logger, LLM, CLI)

The clean separation allows parallel development while maintaining integration points through the cluster communication system.

---

Built with: Java 17, Akka Typed 2.8.5, Gradle 8.0, OpenAI API, Jackson CBOR