refactor(llm): Replace Vec<Event> with Reply wrapper (#137)

This change introduces a `Reply` struct that wraps `Vec<Event>` to
provide a more semantic representation of LLM responses. The Reply type
includes a `From` implementation for `AssistantMessage` conversion and
maintains backward compatibility through Deref traits.

All provider implementations have been updated to return `Reply` instead
of raw event vectors, creating a cleaner abstraction for handling LLM
response collections.

Signed-off-by: Jean Mertz <git@jeanmertz.com>

Author: JeanMertz

crates/jp_llm/src/provider.rs

@@ -13,7 +13,7 @@ use async_trait::async_trait;
 use futures::{Stream, StreamExt as _};
 use google::Google;
 use jp_config::llm::provider;
-use jp_conversation::{message::ToolCallRequest, model::ProviderId, Model};
+use jp_conversation::{message::ToolCallRequest, model::ProviderId, AssistantMessage, Model};
 use jp_query::query::{ChatQuery, StructuredQuery};
 use ollama::Ollama;
 use openai::Openai;
@@ -117,6 +117,56 @@ impl StreamEvent {
     }
 }
 
+/// A collection of events in a single reply.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct Reply(Vec<Event>);
+
+impl Reply {
+    /// Returns the list of events in the reply.
+    #[must_use]
+    pub fn into_inner(self) -> Vec<Event> {
+        self.0
+    }
+}
+
+impl std::ops::Deref for Reply {
+    type Target = Vec<Event>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl std::ops::DerefMut for Reply {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}
+
+impl From<Reply> for AssistantMessage {
+    fn from(reply: Reply) -> Self {
+        let mut message = AssistantMessage::default();
+
+        for event in reply.0 {
+            match event {
+                Event::Content(content) => {
+                    message.content.get_or_insert_default().push_str(&content);
+                }
+                Event::Reasoning(reasoning) => message
+                    .reasoning
+                    .get_or_insert_default()
+                    .push_str(&reasoning),
+                Event::ToolCall(call) => message.tool_calls.push(call),
+                Event::Metadata(key, metadata) => {
+                    message.metadata.insert(key, metadata);
+                }
+            }
+        }
+
+        message
+    }
+}
+
 /// Represents a completed event from the LLM.
 #[derive(Debug, Clone, PartialEq)]
 pub enum Event {
@@ -217,7 +267,7 @@ pub trait Provider: std::fmt::Debug + Send + Sync {
     /// Perform a non-streaming chat completion.
     ///
     /// Default implementation collects results from the streaming version.
-    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Vec<Event>> {
+    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Reply> {
         let mut stream = self.chat_completion_stream(model, query).await?;
         let mut events = Vec::new();
         let mut reasoning = String::new();
@@ -252,7 +302,7 @@ pub trait Provider: std::fmt::Debug + Send + Sync {
             events.push(Event::Content(content));
         }
 
-        Ok(events)
+        Ok(Reply(events))
     }
 
     /// Perform a structured completion.
@@ -283,10 +333,13 @@ pub trait Provider: std::fmt::Debug + Send + Sync {
                 }
             };
 
-            let data = events.into_iter().find_map(|event| match event {
-                Event::ToolCall(call) if call.name == SCHEMA_TOOL_NAME => Some(call.arguments),
-                _ => None,
-            });
+            let data = events
+                .into_inner()
+                .into_iter()
+                .find_map(|event| match event {
+                    Event::ToolCall(call) if call.name == SCHEMA_TOOL_NAME => Some(call.arguments),
+                    _ => None,
+                });
 
             match data {
                 Some(data) => return Ok(query.map(data)),

crates/jp_llm/src/provider/anthropic.rs

@@ -20,7 +20,7 @@ use serde_json::Value;
 use time::macros::date;
 use tracing::{trace, warn};
 
-use super::{Event, EventStream, ModelDetails, Provider, ReasoningDetails, StreamEvent};
+use super::{Event, EventStream, ModelDetails, Provider, ReasoningDetails, Reply, StreamEvent};
 use crate::{
     error::{Error, Result},
     provider::{handle_delta, AccumulationState, Delta},
@@ -149,14 +149,15 @@ impl Provider for Anthropic {
         Ok(models.into_iter().map(map_model).collect())
     }
 
-    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Vec<Event>> {
+    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Reply> {
         let request = self.create_request(model, query).await?;
         self.client
             .messages()
             .create(request)
             .await
             .map_err(Into::into)
             .and_then(map_response)
+            .map(Reply)
     }
 
     async fn chat_completion_stream(&self, model: &Model, query: ChatQuery) -> Result<EventStream> {

crates/jp_llm/src/provider/google.rs

@@ -15,7 +15,7 @@ use jp_query::query::ChatQuery;
 use serde_json::Value;
 use tracing::trace;
 
-use super::{Event, EventStream, ModelDetails, Provider, ReasoningDetails};
+use super::{Event, EventStream, ModelDetails, Provider, ReasoningDetails, Reply};
 use crate::{
     error::{Error, Result},
     provider::Delta,
@@ -109,14 +109,15 @@ impl Provider for Google {
             .collect())
     }
 
-    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Vec<Event>> {
+    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Reply> {
         let request = self.create_request(model, query).await?;
 
         self.client
             .generate_content(model.id.slug(), &request)
             .await
             .map_err(Into::into)
             .and_then(map_response)
+            .map(Reply)
     }
 
     async fn chat_completion_stream(&self, model: &Model, query: ChatQuery) -> Result<EventStream> {

crates/jp_llm/src/provider/ollama.rs

@@ -24,7 +24,7 @@ use serde_json::Value;
 use tracing::trace;
 use url::Url;
 
-use super::{handle_delta, Event, EventStream, ModelDetails, Provider, StreamEvent};
+use super::{handle_delta, Event, EventStream, ModelDetails, Provider, Reply, StreamEvent};
 use crate::{
     error::{Error, Result},
     provider::{AccumulationState, Delta},
@@ -44,13 +44,14 @@ impl Provider for Ollama {
         Ok(models.into_iter().map(map_model).collect())
     }
 
-    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Vec<Event>> {
+    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Reply> {
         let request = create_request(model, query)?;
         self.client
             .send_chat_messages(request)
             .await
             .map_err(Into::into)
             .and_then(map_response)
+            .map(Reply)
     }
 
     async fn chat_completion_stream(&self, model: &Model, query: ChatQuery) -> Result<EventStream> {

crates/jp_llm/src/provider/openai.rs

@@ -22,7 +22,8 @@ use time::{macros::date, OffsetDateTime};
 use tracing::{debug, trace, warn};
 
 use super::{
-    handle_delta, Delta, Event, EventStream, ModelDetails, Provider, ReasoningDetails, StreamEvent,
+    handle_delta, Delta, Event, EventStream, ModelDetails, Provider, ReasoningDetails, Reply,
+    StreamEvent,
 };
 use crate::{
     error::{Error, Result},
@@ -94,14 +95,15 @@ impl Provider for Openai {
             .collect())
     }
 
-    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Vec<Event>> {
+    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Reply> {
         let client = self.client.clone();
         let request = self.create_request(model, query).await?;
         client
             .create(request)
             .await?
             .map_err(Into::into)
             .and_then(map_response)
+            .map(Reply)
     }
 
     async fn chat_completion_stream(&self, model: &Model, query: ChatQuery) -> Result<EventStream> {

crates/jp_llm/src/provider/openrouter.rs

@@ -27,7 +27,7 @@ use serde::Serialize;
 use serde_json::Value;
 use tracing::{debug, trace, warn};
 
-use super::{CompletionChunk, Delta, Event, EventStream, ModelDetails, StreamEvent};
+use super::{CompletionChunk, Delta, Event, EventStream, ModelDetails, Reply, StreamEvent};
 use crate::{
     error::Result,
     provider::{handle_delta, AccumulationState, Provider},
@@ -198,7 +198,7 @@ impl Provider for Openrouter {
         Ok(stream)
     }
 
-    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Vec<Event>> {
+    async fn chat_completion(&self, model: &Model, query: ChatQuery) -> Result<Reply> {
         let request = self.build_request(query, model).await?;
         let completion =
             self.client.chat_completion(request).await.inspect_err(
@@ -210,12 +210,12 @@ impl Provider for Openrouter {
         let choice_data = completion.choices.into_iter().next();
         let Some(choice) = choice_data else {
             trace!("OpenRouter delta had no choices, skipping.");
-            return Ok(vec![]);
+            return Ok(Reply::default());
         };
 
         let Choice::NonStreaming(choice) = choice else {
             warn!("Received streaming choice in non-streaming context, ignoring.");
-            return Ok(vec![]);
+            return Ok(Reply::default());
         };
 
         if let Some(ErrorResponse { code, message, .. }) = choice.error {
@@ -240,7 +240,7 @@ impl Provider for Openrouter {
             }));
         }
 
-        Ok(events)
+        Ok(Reply(events))
     }
 }