Added garmin connect integration

Author: Alpha200

.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-**Yume** (夢 - "dream" in Japanese) is an AI-powered personal assistant that integrates Matrix chat, Home Assistant, calendar events, public transport, and shopping list management. It features advanced memory management, intelligent scheduling, location-based triggers, and an AI agent architecture powered by langchain4j.
+**Yume** (夢 - "dream" in Japanese) is an AI-powered personal assistant that integrates Matrix chat, Home Assistant, calendar events, public transport, sports activities (Strava), health data (Garmin Connect), and shopping list management. It features advanced memory management, intelligent scheduling, location-based triggers, e-ink display support, and an AI agent architecture powered by langchain4j.
 
 **Project Type**: Full-stack application (Spring Boot backend + Vue.js frontend)
 **Size**: Medium (~3K lines Kotlin, ~500 lines Vue.js)
@@ -132,23 +132,24 @@ docker run -d --name yume -p 8079:8079 --env-file .env yume
 - See lines 1-101 for complete list of required settings
 
 **Package Structure**:
-- `agent/` - AI agents (RequestRouterAgent, GenericChatAgent, MemoryManagerAgent, SchedulerAgent, DayPlanAgent, EfaAgent, KitchenOwlAgent, ConversationSummarizerAgent, MemorySummarizerAgent, EInkDisplayAgent)
-- `service/` - Business logic (matrix/, memory/, scheduler/, dayplan/, conversation/, calendar/, weather/, efa/, kitchenowl/, provider/, interaction/, location/, router/, eink/)
-- `tool/` - langchain4j tools (MemoryManagerTools, DayPlanTools, EfaTools, KitchenOwlTools, KitchenOwlReadTools)
+- `agent/` - AI agents (RequestRouterAgent, GenericChatAgent, MemoryManagerAgent, SchedulerAgent, DayPlanAgent, EfaAgent, KitchenOwlAgent, ConversationSummarizerAgent, MemorySummarizerAgent, EInkDisplayAgent, SportsActivityAgent)
+- `service/` - Business logic (matrix/, memory/, scheduler/, dayplan/, conversation/, calendar/, weather/, efa/, kitchenowl/, provider/, interaction/, location/, router/, eink/, strava/, garminconnect/)
+- `tool/` - langchain4j tools (MemoryManagerTools, DayPlanTools, EfaTools, KitchenOwlTools, KitchenOwlReadTools, StravaActivityTools)
 - `component/` - Data models (conversation/, calendar/, weather/)
-- `controller/` - REST endpoints (webhook handlers)
-- `repository/` - MongoDB repositories (memory/)
+- `controller/` - REST endpoints (webhook handlers, EInkDisplayController, StravaWebhookController)
+- `repository/` - MongoDB repositories (memory/, strava/)
 - `configuration/` - Spring configuration classes
 - `converter/` - Data converters
-- `client/` - External API clients
+- `client/` - External API clients (StravaClient)
 - `utils/` - Utility classes (timezone handling)
 
 **Key Dependencies** (from `build.gradle.kts`):
 - Spring Boot 3.5.9 (web, data-mongodb, oauth2-resource-server, cache)
 - Kotlin 2.2.21 (with serialization)
 - langchain4j 1.10.0-beta18 (OpenAI, pgvector, Kotlin extensions)
+- Model Context Protocol (MCP) SDK (Garmin Connect integration)
 - Trixnity 4.22.7 (Matrix client)
-- Ktor 3.3.3 (HTTP client for Matrix)
+- Ktor 3.3.3 (HTTP client for Matrix and Strava)
 - caldav4j 1.0.5 (calendar integration)
 - Caffeine 3.2.3 (caching)
 - MockK 1.14.7 (testing)
@@ -224,6 +225,9 @@ docker run -d --name yume -p 8079:8079 --env-file .env yume
 - OpenWeatherMap (API key)
 - EFA public transport (API URL)
 - Location coordinates (home latitude/longitude)
+- **Strava Integration** (`yume.strava.client-id`, `yume.strava.client-secret`, `yume.strava.webhook-verify-token`, `yume.strava.webhook-url`)
+- **Garmin Connect** (`yume.garmin-connect.mcp-server-url` - MCP server must be running separately)
+- **E-Ink Display** (configured via resource provider - no additional config needed)
 
 ## Known Issues & Workarounds
 

README.md

@@ -15,10 +15,13 @@
 - 📍 **Geofence Events**: Location-based triggers with distance context from proximity sensors
 - 🚌 **Public Transport Departures**: Real-time transit information via EFA (Elektronisches Fahrplanauskun ftssystem) API with dynamic station lookup and line/direction filtering
 - 🛒 **KitchenOwl Integration**: Manage shopping lists and recipes with intelligent duplicate handling
+- 🏃 **Strava Integration**: Automatic cycling activity logging and analysis with webhook support
+- 💪 **Garmin Health Metrics**: Daily health insights including training load, sleep quality, and fitness status via Garmin Connect
+- 📱 **E-Ink Display Support**: Summarized daily briefings rendered for e-paper displays with optimal readability
 - 🧠 **Advanced Memory System**: Persistent storage with preferences, observations, and reminders
 - 📅 **AI-Powered Day Planner**: Automatic daily planning based on calendar and memories with high-confidence updates
 - ⏰ **Intelligent AI Scheduler**: Context-aware scheduling with deferred execution and adaptive re-evaluation
-- 📊 **Vue.js Dashboard**: Real-time monitoring of memories, schedules, plans, and interactions
+- 📊 **Vue.js Dashboard**: Real-time monitoring of memories, schedules, plans, and interactions with Strava connection management
 - 🔐 **OpenID Connect Authentication**: Secure access to web interface
 
 ## Architecture
@@ -34,6 +37,9 @@ Yume is built with a modular architecture consisting of several key components:
 - **Home Assistant Service** (`service/provider/`): Integration with Home Assistant API
 - **Calendar & Weather Services** (`service/calendar/`, `service/weather/`): External service integrations
 - **Conversation Service** (`service/conversation/`): Message history and conversation management
+- **Strava Integration Service** (`service/strava/`): OAuth 2.0 authentication and webhook handling for Strava cycling activities
+- **Garmin Connect Service** (`service/garminconnect/`): Health metrics fetcher via Model Context Protocol (MCP)
+- **E-Ink Display Service** (`service/eink/`): Generates optimized content for e-paper displays
 
 ### AI Agents (langchain4j-powered)
 
@@ -45,6 +51,8 @@ Yume is built with a modular architecture consisting of several key components:
 - **SchedulerAgent** (`agent/SchedulerAgent.kt`): Intelligent scheduling with deferred execution, automatic re-evaluation, and dual-approach timing optimization (deterministic + AI-powered). Receives execution summaries from scheduled/geofence events for improved future scheduling decisions.
 - **EfaAgent** (`agent/EfaAgent.kt`): Specialized agent for querying public transport departures. Parses natural language queries to extract station names, line numbers, and destination directions.
 - **KitchenOwlAgent** (`agent/KitchenOwlAgent.kt`): Manages shopping lists and recipes with autonomous decision-making. Intelligently handles duplicate items by checking the list before adding.
+- **SportsActivityAgent** (`agent/SportsActivityAgent.kt`): Analyzes cycling activities from Strava, tracks performance metrics, and provides personalized fitness insights. Triggered by Strava webhooks and scheduled events.
+- **EInkDisplayAgent** (`agent/EInkDisplayAgent.kt`): Generates concise, visually optimized summaries for e-ink display devices with support for Tailwind CSS styling and responsive layouts.
 
 Event-triggered agent methods (`handleScheduledEvent`, `handleGeofenceEvent`) re-evaluate current context before acting, ensuring actions remain relevant and avoiding unnecessary messages.
 
@@ -65,6 +73,7 @@ langchain4j-powered tools for AI agents:
 - **Home Assistant Tools**: Smart home control and sensor data
 - **EFA Tools**: Public transport departure queries with optional line and direction filtering
 - **KitchenOwl Tools**: Shopping list management and recipe access with batch operations
+- **Strava Activity Tools**: Fetch recent cycling activities and performance metrics
 
 ### Data Management
 
@@ -226,6 +235,87 @@ rest_command:
 
 The API validates that `eventType` is either "enter" or "leave" and returns a response indicating success or failure along with any AI-generated message.
 
+#### Strava Integration
+
+Yume can automatically fetch and analyze your Strava cycling activities through webhook integration:
+
+**Setup:**
+
+1. Configure Strava OAuth credentials in `application.properties`:
+   ```properties
+   yume.strava.enabled=true
+   yume.strava.client-id=YOUR_CLIENT_ID
+   yume.strava.client-secret=YOUR_CLIENT_SECRET
+   yume.strava.webhook-verify-token=YOUR_VERIFY_TOKEN
+   yume.strava.webhook-url=http://your-yume-server:8079/api/strava/webhook
+   yume.strava.oauth-redirect-url=http://localhost:3000/api/strava/oauth/callback
+   ```
+
+2. Connect your Strava account via the web dashboard (Preferences → Strava Integration)
+
+3. Yume will automatically register webhooks with Strava for activity creation events
+
+**Features:**
+- Automatic cycling activity logging and analysis
+- Activity performance metrics (distance, duration, elevation, power, heart rate)
+- AI-powered fitness insights and personalized feedback
+- Strava connection management in the web dashboard
+- Webhook endpoint: `POST /api/strava/webhook`
+
+#### Garmin Connect Integration
+
+Yume fetches daily health metrics from Garmin Connect via Model Context Protocol (MCP):
+
+**Setup:**
+
+1. Configure Garmin MCP server URL in `application.properties`:
+   ```properties
+   yume.garmin-connect.mcp-server-url=http://localhost:60380
+   ```
+
+2. Ensure the Garmin Connect MCP server is running and authenticated
+
+**Health Metrics Provided:**
+- **Training Balance**: Daily training load feedback and balance status
+- **Training Status**: Current training condition and acute training load
+- **Sleep Quality**: Sleep score, duration, stages (deep/light/REM), and nap data with timestamps
+- **Daily Activity**: Step count, intensity minutes, and body battery measurements
+- **Heart Rate Variability**: HRV status for recovery assessment
+
+These metrics are automatically populated into the user context for memory management and scheduling decisions.
+
+#### E-Ink Display Endpoint
+
+Yume generates optimized summaries for e-ink display devices:
+
+**Endpoint:** `GET /api/e-ink-display/content` (produces `text/plain`)
+
+**Response Format:** Plain HTML with Tailwind CSS styling, optimized for small, low-resolution displays
+
+**Features:**
+- Automatic content compilation from multiple sources:
+  - Current date/time
+  - User preferences and language
+  - Weather forecast
+  - Today's and tomorrow's day plan
+  - User observations and preferences summary
+- AI-powered text generation with formatting rules:
+  - Maximum 5-7 lines of text for readability from 1 meter distance
+  - black & white only (no colors or shades)
+  - Natural language date/time formatting
+  - Concise, high-priority information only
+  - Long-term relevance (no real-time updates)
+
+**Integration Example** (for e-ink display device):
+
+```bash
+# Fetch display content periodically (e.g., update once or twice daily)
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://localhost:8079/api/e-ink-display/content
+```
+
+The response is ready-to-render HTML that your e-ink device can display immediately.
+
 ### Vue.js Dashboard
 
 Access at `http://localhost:8079` to monitor:

yume-spring/build.gradle.kts

@@ -31,6 +31,7 @@ val calDav4jVersion = "1.0.5"
 val chromaClientVersion = "1.1.0"
 val caffeineCacheVersion = "3.2.3"
 val mockkVersion = "1.14.7"
+val mcpVersion = "0.4.0"
 
 dependencies {
 	implementation("org.springframework.boot:spring-boot-starter-web")
@@ -61,7 +62,6 @@ dependencies {
 	// Kotlin logging
 	implementation("io.github.oshai:kotlin-logging-jvm:$kotlinLoggingVersion")
 
-
 	// Spring data
 	implementation("org.springframework.boot:spring-boot-starter-data-mongodb")
 
@@ -72,6 +72,9 @@ dependencies {
 	implementation("org.springframework.boot:spring-boot-starter-cache")
 	implementation("com.github.ben-manes.caffeine:caffeine:$caffeineCacheVersion")
 
+	// MCP Client
+	implementation("io.modelcontextprotocol:kotlin-sdk:${mcpVersion}")
+
 	// Observability (Spring Boot 4)
 	//implementation("org.springframework.boot:spring-boot-starter-actuator")
 	//implementation("org.springframework.boot:spring-boot-starter-opentelemetry")

yume-spring/src/main/kotlin/eu/sendzik/yume/agent/model/YumeChatResource.kt

@@ -4,4 +4,5 @@ enum class YumeChatResource {
     WEATHER_FORECAST,
     DAY_PLAN_TODAY,
     DAY_PLAN_TOMORROW,
+    USER_HEALTH_SNAPSHOT,
 }

yume-spring/src/main/kotlin/eu/sendzik/yume/configuration/CacheConfiguration.kt

@@ -13,10 +13,21 @@ import java.util.concurrent.TimeUnit
 class CacheConfiguration {
     @Bean
     fun cacheManager(): CacheManager {
-        return CaffeineCacheManager().apply {
-            setCaffeine(
-                Caffeine.newBuilder().expireAfterWrite(30, TimeUnit.SECONDS)
-            )
-        }
+        val cacheManager = CaffeineCacheManager()
+
+        // Register garmin_snapshot cache with 10-minute TTL
+        cacheManager.registerCustomCache(
+            "garmin_snapshot",
+            Caffeine.newBuilder()
+                .expireAfterWrite(10, TimeUnit.MINUTES)
+                .build()
+        )
+
+        // Set default TTL for other caches
+        cacheManager.setCaffeine(
+            Caffeine.newBuilder().expireAfterWrite(30, TimeUnit.SECONDS)
+        )
+
+        return cacheManager
     }
 }

yume-spring/src/main/kotlin/eu/sendzik/yume/service/garminconnect/GarminConnectDataFetcherService.kt

@@ -0,0 +1,54 @@
+package eu.sendzik.yume.service.garminconnect
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import eu.sendzik.yume.service.garminconnect.model.GarminHealthStatus
+import io.ktor.client.HttpClient
+import io.ktor.client.plugins.sse.SSE
+import io.modelcontextprotocol.kotlin.sdk.Implementation
+import io.modelcontextprotocol.kotlin.sdk.TextContent
+import io.modelcontextprotocol.kotlin.sdk.client.Client
+import io.modelcontextprotocol.kotlin.sdk.client.SseClientTransport
+import kotlinx.coroutines.runBlocking
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.cache.annotation.Cacheable
+import org.springframework.stereotype.Service
+import java.time.LocalDate
+
+@Service
+class GarminConnectDataFetcherService(
+    @param:Value("\${yume.garmin-connect.mcp-server-url}")
+    private val mcpServerUrl: String,
+    private val jsonMapper: ObjectMapper,
+) {
+
+    @Cacheable("garmin_snapshot", sync = true)
+    fun getSnapshot(): Result<GarminHealthStatus?> = runBlocking {
+        runCatching {
+            fetchSnapshotData()?.let { content ->
+                @Suppress("UNCHECKED_CAST")
+                val contentText: Map<String, Any> = jsonMapper.readValue(content, Map::class.java) as Map<String, Any>
+                GarminHealthStatus.fromApi(contentText)
+            }
+        }
+    }
+
+    private suspend fun fetchSnapshotData(): String? {
+        val httpClient = HttpClient { install(SSE) }
+        val transport = SseClientTransport(httpClient, mcpServerUrl)
+        val client = Client(clientInfo = Implementation("GarminConnectService", "1.0"))
+
+        try {
+            client.connect(transport)
+            val today = LocalDate.now()
+            val result = client.callTool("snapshot", mapOf(
+                "from_date" to today.toString(),
+                "to_date" to today.toString(),
+            ))
+            val textContent = result?.content?.firstOrNull() as? TextContent
+            return textContent?.text
+        } finally {
+            client.close()
+            httpClient.close()
+        }
+    }
+}

yume-spring/src/main/kotlin/eu/sendzik/yume/service/garminconnect/GarminConnectService.kt

@@ -0,0 +1,82 @@
+package eu.sendzik.yume.service.garminconnect
+
+import eu.sendzik.yume.service.garminconnect.model.GarminHealthStatus
+import jakarta.annotation.PostConstruct
+import org.springframework.stereotype.Service
+import java.time.ZoneId
+import java.time.format.DateTimeFormatter
+
+@Service
+class GarminConnectService(
+    private val garminConnectDataFetcherService: GarminConnectDataFetcherService,
+) {
+    private val dateTimeFormatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm")
+
+    fun getFormattedHealthSnapshot(): Result<String> {
+        return garminConnectDataFetcherService.getSnapshot().map { healthStatus ->
+            if (healthStatus != null) {
+                formatHealthStatus(healthStatus)
+            } else {
+                "No health data available"
+            }
+        }
+    }
+
+    private fun formatHealthStatus(healthStatus: GarminHealthStatus): String = buildString {
+        appendLine("=== Training Balance ===")
+        appendLine("Status: ${healthStatus.trainingBalance.trainingBalanceFeedback}")
+        appendLine()
+
+        appendLine("=== Training Status ===")
+        appendLine("Status: ${healthStatus.trainingStatus.trainingStatusFeedback}")
+        appendLine("Acute Training Load: ${healthStatus.trainingStatus.acuteTrainingLoad}")
+        appendLine()
+
+        appendLine("=== Sleep Summary ===")
+        appendLine("Overall Sleep Score: ${healthStatus.sleepStatus.overallSleepScore}/100")
+
+        if (healthStatus.sleepStatus.sleepStartTimestampGMT != null && healthStatus.sleepStatus.sleepEndTimestampGMT != null) {
+            val startTime = healthStatus.sleepStatus.sleepStartTimestampGMT
+                .atZone(ZoneId.systemDefault())
+                .format(dateTimeFormatter)
+            val endTime = healthStatus.sleepStatus.sleepEndTimestampGMT
+                .atZone(ZoneId.systemDefault())
+                .format(dateTimeFormatter)
+            appendLine("Sleep Period: $startTime to $endTime")
+        }
+
+        appendLine("Total Sleep Duration: ${healthStatus.sleepStatus.sleepScores.sleepTimeMinutes} minutes")
+        appendLine("Sleep Duration Quality: ${healthStatus.sleepStatus.sleepScores.totalDuration}")
+        appendLine("Deep Sleep: ${healthStatus.sleepStatus.sleepScores.deepPercentage}")
+        appendLine("Light Sleep: ${healthStatus.sleepStatus.sleepScores.lightPercentage}")
+        appendLine("REM Sleep: ${healthStatus.sleepStatus.sleepScores.remPercentage}")
+        appendLine("Awake Count: ${healthStatus.sleepStatus.sleepScores.awakeCount}")
+        appendLine("Sleep Stress: ${healthStatus.sleepStatus.sleepScores.stress}")
+        appendLine("Sleep Restlessness: ${healthStatus.sleepStatus.sleepScores.restlessness}")
+
+        if (healthStatus.sleepStatus.napTimeMinutes > 0) {
+            appendLine()
+            appendLine("Total Nap Time: ${healthStatus.sleepStatus.napTimeMinutes} minutes")
+            if (healthStatus.sleepStatus.naps.isNotEmpty()) {
+                appendLine("Naps:")
+                healthStatus.sleepStatus.naps.forEachIndexed { index, nap ->
+                    val napStart = nap.startTimestamp.format(dateTimeFormatter)
+                    val napEnd = nap.endTimestamp.format(dateTimeFormatter)
+                    appendLine("  ${index + 1}. $napStart to $napEnd (${nap.durationMinutes} minutes) - ${nap.feedback}")
+                }
+            }
+        }
+        appendLine()
+
+        appendLine("=== Daily Activity Summary ===")
+        appendLine("Total Steps: ${healthStatus.dailySummary.totalSteps}")
+        appendLine("Moderate Intensity Minutes: ${healthStatus.dailySummary.moderateIntensityMinutes}")
+        appendLine("Vigorous Intensity Minutes: ${healthStatus.dailySummary.vigorousIntensityMinutes}")
+        appendLine("Body Battery (Most Recent): ${healthStatus.dailySummary.bodyBatteryMostRecentValue}/100")
+        appendLine()
+
+        appendLine("=== Heart Rate Variability ===")
+        appendLine("HRV Status: ${healthStatus.heartRateVariability.heartRateVariabilityStatus}")
+    }
+}
+