Include title in message events.

jasperblues · jasperblues · commit 3c07ca9a435d · 2026-02-04T07:40:45.000+11:00
diff --git a/README.md b/README.md
@@ -0,0 +1,194 @@
+# Embabel Chat Store
+
+Conversation persistence layer for Embabel Agent. Provides pluggable storage backends for chat sessions - in-memory for development/testing, Neo4j for production.
+
+## Quick Start
+
+```kotlin
+// Get a factory for your storage type
+val factory = conversationFactoryProvider.get(ConversationStoreType.STORED)
+
+// Create a conversation for a 1-1 chat
+val conversation = (factory as StoredConversationFactory)
+    .createForParticipants(
+        id = sessionId,
+        user = currentUser,
+        agent = assistantUser,
+        title = "My Chat"
+    )
+
+// Add messages - automatically routed based on role
+conversation.addMessage(UserMessage("Hello!"))      // from=user, to=agent
+conversation.addMessage(AssistantMessage("Hi!"))    // from=agent, to=user
+```
+
+## Architecture
+
+```
+ConversationFactoryProvider
+    ├── InMemoryConversationFactory  → InMemoryConversation (ephemeral)
+    └── StoredConversationFactory    → StoredConversation (Neo4j)
+```
+
+### Storage Types
+
+| Type | Class | Use Case |
+|------|-------|----------|
+| `IN_MEMORY` | `InMemoryConversation` | Testing, ephemeral chats |
+| `STORED` | `StoredConversation` | Production, persistent chats |
+
+## Message Events
+
+Subscribe to message lifecycle events for real-time updates:
+
+```kotlin
+@EventListener
+fun onMessage(event: MessageEvent) {
+    when (event.status) {
+        MessageStatus.ADDED -> {
+            // Message added - update UI immediately
+            sendToWebSocket(event.toUserId, event)
+        }
+        MessageStatus.PERSISTED -> {
+            // Message saved to storage
+        }
+        MessageStatus.PERSISTENCE_FAILED -> {
+            // Handle error - event.error has details
+        }
+    }
+}
+```
+
+### Event Fields
+
+| Field | Description |
+|-------|-------------|
+| `conversationId` | Session ID |
+| `fromUserId` | Who sent the message |
+| `toUserId` | Who should receive it (for routing) |
+| `title` | Session title (for UI display) |
+| `message` | The message content |
+| `status` | ADDED, PERSISTED, or PERSISTENCE_FAILED |
+
+## Message Attribution
+
+Messages have explicit sender and recipient:
+
+```
+(message:StoredMessage)-[:AUTHORED_BY]->(from:SessionUser)
+(message:StoredMessage)-[:SENT_TO]->(to:SessionUser)
+```
+
+### Role-Based Routing (1-1 Chats)
+
+| Role | From | To |
+|------|------|-----|
+| USER | user | agent |
+| ASSISTANT | agent | user |
+| SYSTEM | null | user |
+
+### Multi-Party Chats
+
+For multi-user or multi-agent scenarios, use `addMessageFromTo` for explicit routing:
+
+```kotlin
+// Create conversation without default participants
+val conversation = factory.create(sessionId)
+
+// Group chat with multiple users
+conversation.addMessageFromTo(UserMessage("Hi everyone!"), from = alice, to = bob)
+conversation.addMessageFromTo(UserMessage("Hello Alice!"), from = bob, to = alice)
+conversation.addMessageFromTo(UserMessage("Hey both!"), from = charlie, to = alice)
+
+// Agent handoff - one agent passing to another
+conversation.addMessageFromTo(
+    AssistantMessage("Transferring you to billing..."),
+    from = supportAgent,
+    to = customer
+)
+conversation.addMessageFromTo(
+    AssistantMessage("Hi, I'm the billing specialist."),
+    from = billingAgent,
+    to = customer
+)
+
+// Multi-agent collaboration
+conversation.addMessageFromTo(
+    AssistantMessage("I'll research that."),
+    from = researchAgent,
+    to = coordinatorAgent
+)
+conversation.addMessageFromTo(
+    AssistantMessage("Here's what I found..."),
+    from = researchAgent,
+    to = customer
+)
+```
+
+#### Future Enhancements
+
+Planned support for:
+- Group recipients (send to multiple users at once)
+- Participant lists on conversations
+- Agent-to-agent communication patterns
+- Broadcast messages
+
+## Auto Title Generation
+
+Provide a `TitleGenerator` to automatically generate session titles:
+
+```kotlin
+val factory = StoredConversationFactory(
+    repository = chatSessionRepository,
+    eventPublisher = applicationEventPublisher,
+    titleGenerator = { message ->
+        // Generate title from first message
+        llm.generate("Summarize in 5 words: ${message.content}")
+    }
+)
+```
+
+## Session User
+
+Implement `SessionUser` for your user type:
+
+```kotlin
+@NodeFragment(labels = ["SessionUser", "MyUser"])
+data class MyUser(
+    @NodeId override val id: String,
+    override val displayName: String,
+    val email: String
+) : SessionUser
+```
+
+Register with Drivine:
+
+```kotlin
+persistenceManager.registerSubtype(
+    SessionUser::class.java,
+    "MyUser|SessionUser",
+    MyUser::class.java
+)
+```
+
+## Spring Boot Auto-Configuration
+
+Add the dependency and configure:
+
+```yaml
+embabel:
+  chat:
+    store:
+      enabled: true  # default
+```
+
+Beans auto-configured:
+- `storedConversationFactory` - for persistent conversations
+- `inMemoryConversationFactory` - for ephemeral conversations
+- `conversationFactoryProvider` - aggregates all factories
+
+## Dependencies
+
+- `embabel-agent-api` - Core conversation interfaces
+- `drivine` - Neo4j graph persistence
+- Spring Boot (optional, for auto-configuration)
diff --git a/pom.xml b/pom.xml
@@ -12,7 +12,7 @@
 
     <groupId>com.embabel.agent</groupId>
     <artifactId>embabel-chat-store</artifactId>
-    <version>0.1.0-SNAPSHOT</version>
+    <version>0.2.0-SNAPSHOT</version>
     <packaging>jar</packaging>
     <name>Embabel Chat Store</name>
     <description>Chat session storage library for Embabel Agent using Neo4j and Drivine</description>
@@ -194,4 +194,4 @@
         </snapshotRepository>
     </distributionManagement>
 
-</project>
+</project>
diff --git a/src/main/kotlin/com/embabel/chat/event/ConversationEvents.kt b/src/main/kotlin/com/embabel/chat/event/ConversationEvents.kt
@@ -85,6 +85,7 @@ enum class MessageStatus {
  * @param status the current status of the message
  * @param fromUserId the ID of the user who sent this message (author)
  * @param toUserId the ID of the user who should receive this message (for routing, e.g., WebSocket)
+ * @param title the session/conversation title (for UI display)
  * @param message the message (always present for ADDED, present for PERSISTED)
  * @param content the message content (useful for PERSISTENCE_FAILED when message ref may be stale)
  * @param role the message role
@@ -96,6 +97,7 @@ data class MessageEvent(
     val status: MessageStatus,
     val fromUserId: String? = null,
     val toUserId: String? = null,
+    val title: String? = null,
     val message: Message? = null,
     val content: String? = null,
     val role: Role? = null,
@@ -111,12 +113,14 @@ data class MessageEvent(
             conversationId: String,
             message: Message,
             fromUserId: String? = null,
-            toUserId: String? = null
+            toUserId: String? = null,
+            title: String? = null
         ) = MessageEvent(
             conversationId = conversationId,
             status = MessageStatus.ADDED,
             fromUserId = fromUserId,
             toUserId = toUserId,
+            title = title,
             message = message,
             content = message.content,
             role = message.role
@@ -129,12 +133,14 @@ data class MessageEvent(
             conversationId: String,
             message: Message,
             fromUserId: String? = null,
-            toUserId: String? = null
+            toUserId: String? = null,
+            title: String? = null
         ) = MessageEvent(
             conversationId = conversationId,
             status = MessageStatus.PERSISTED,
             fromUserId = fromUserId,
             toUserId = toUserId,
+            title = title,
             message = message,
             content = message.content,
             role = message.role
@@ -149,12 +155,14 @@ data class MessageEvent(
             role: Role,
             error: Throwable,
             fromUserId: String? = null,
-            toUserId: String? = null
+            toUserId: String? = null,
+            title: String? = null
         ) = MessageEvent(
             conversationId = conversationId,
             status = MessageStatus.PERSISTENCE_FAILED,
             fromUserId = fromUserId,
             toUserId = toUserId,
+            title = title,
             content = content,
             role = role,
             error = error
diff --git a/src/main/kotlin/com/embabel/chat/store/adapter/StoredConversation.kt b/src/main/kotlin/com/embabel/chat/store/adapter/StoredConversation.kt
@@ -83,6 +83,7 @@ import java.util.UUID
  * @param eventPublisher Spring's event publisher for broadcasting events
  * @param user the human user participant (author of USER messages, recipient of ASSISTANT messages)
  * @param agent the AI/system user participant (author of ASSISTANT messages, recipient of USER messages)
+ * @param title the session title (included in events for UI display)
  * @param titleGenerator optional generator for auto-generating session title from first message
  * @param assetTracker tracker for conversation assets (defaults to in-memory)
  * @param scope coroutine scope for async operations (defaults to IO dispatcher with SupervisorJob)
@@ -93,6 +94,7 @@ class StoredConversation(
     private val eventPublisher: ApplicationEventPublisher? = null,
     private val user: SessionUser? = null,
     private val agent: SessionUser? = null,
+    private var title: String? = null,
     private val titleGenerator: TitleGenerator? = null,
     override val assetTracker: AssetTracker = InMemoryAssetTracker(),
     private val scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob()),
@@ -190,7 +192,7 @@ class StoredConversation(
 
         // Publish ADDED event synchronously before async persistence
         eventPublisher?.publishEvent(
-            MessageEvent.added(id, message, from?.id, to?.id)
+            MessageEvent.added(id, message, from?.id, to?.id, title)
         )
 
         scope.launch {
@@ -199,21 +201,18 @@ class StoredConversation(
                 val persistedMessage = updatedSession.messages.last().toMessage()
 
                 // Generate title from first message if no title exists
-                if (isFirstMessage && titleGenerator != null) {
-                    val session = repository.findBySessionId(id).orElse(null)
-                    if (session?.session?.title.isNullOrBlank()) {
-                        try {
-                            val title = titleGenerator.generate(message)
-                            repository.updateSessionTitle(id, title)
-                            logger.debug("Generated title '{}' for session {}", title, id)
-                        } catch (e: Exception) {
-                            logger.warn("Failed to generate title for session {}: {}", id, e.message)
-                        }
+                if (isFirstMessage && titleGenerator != null && title.isNullOrBlank()) {
+                    try {
+                        title = titleGenerator.generate(message)
+                        repository.updateSessionTitle(id, title!!)
+                        logger.debug("Generated title '{}' for session {}", title, id)
+                    } catch (e: Exception) {
+                        logger.warn("Failed to generate title for session {}: {}", id, e.message)
                     }
                 }
 
                 eventPublisher?.publishEvent(
-                    MessageEvent.persisted(id, persistedMessage, from?.id, to?.id)
+                    MessageEvent.persisted(id, persistedMessage, from?.id, to?.id, title)
                 )
                 logger.debug("Message {} persisted to session {}", messageData.messageId, id)
             } catch (e: Exception) {
@@ -225,7 +224,8 @@ class StoredConversation(
                         role = message.role,
                         error = e,
                         fromUserId = from?.id,
-                        toUserId = to?.id
+                        toUserId = to?.id,
+                        title = title
                     )
                 )
             }
diff --git a/src/main/kotlin/com/embabel/chat/store/adapter/StoredConversationFactory.kt b/src/main/kotlin/com/embabel/chat/store/adapter/StoredConversationFactory.kt
@@ -77,19 +77,31 @@ class StoredConversationFactory @JvmOverloads constructor(
      * @param id the conversation/session ID
      * @param user the human user participant
      * @param agent the AI/system user participant (optional, can be set later)
+     * @param title the session title (included in events for UI display)
      */
     @JvmOverloads
-    fun createForParticipants(id: String, user: SessionUser, agent: SessionUser? = null): Conversation {
-        return createInternal(id, user, agent)
+    fun createForParticipants(
+        id: String,
+        user: SessionUser,
+        agent: SessionUser? = null,
+        title: String? = null
+    ): Conversation {
+        return createInternal(id, user, agent, title)
     }
 
-    private fun createInternal(id: String, user: SessionUser?, agent: SessionUser?): Conversation {
+    private fun createInternal(
+        id: String,
+        user: SessionUser?,
+        agent: SessionUser?,
+        title: String? = null
+    ): Conversation {
         return StoredConversation(
             id = id,
             repository = repository,
             eventPublisher = eventPublisher,
             user = user,
             agent = agent,
+            title = title,
             titleGenerator = titleGenerator,
             assetTracker = InMemoryAssetTracker(),
             scope = scope
