syntax = "proto3";

package nominal.conversations.v1;

import "google/protobuf/timestamp.proto";

// ConversationService provides conversation lifecycle and persistence for AI agents
service ConversationService {
  // Create a new conversation for any agent type
  rpc CreateConversation(CreateConversationRequest) returns (CreateConversationResponse);

  // List latest conversations for a context in descending order of updated_at timestamp
  rpc ListConversations(ListConversationsRequest) returns (ListConversationsResponse);

  // Get conversation by rid including full message history
  rpc GetConversation(GetConversationRequest) returns (GetConversationResponse);

  // Add a message to an existing conversation
  rpc AddMessage(AddMessageRequest) returns (AddMessageResponse);

  // Set or update the title of a conversation
  rpc SetConversationTitle(SetConversationTitleRequest) returns (SetConversationTitleResponse);
}

message CreateConversationRequest {
  string workspace_rid = 1;
  string workbook_rid = 2;
  ModelMessage message = 3;
  optional string title = 4;
}

message CreateConversationResponse {
  string conversation_rid = 1;
}

message ListConversationsRequest {
  string workbook_rid = 1;
  // (default 10)
  optional int32 limit = 2;
  // (default empty)
  optional string cursor = 3;
}

message ListConversationsResponse {
  repeated ConversationMetadata conversations = 1;
  // Next cursor for pagination
  optional string next_cursor = 2;
}

message GetConversationRequest {
  string conversation_rid = 1;
}

message GetConversationResponse {
  Conversation conversation = 1;
}

message AddMessageRequest {
  string conversation_rid = 1;
  ModelMessage message = 2;
}

message AddMessageResponse {
  // Confirmation of the message being added
  string message_id = 1;
}

message SetConversationTitleRequest {
  string conversation_rid = 1;
  string title = 2;
}

message SetConversationTitleResponse {
  // Empty response
}

message ConversationMetadata {
  // Conversation rid
  string rid = 1;
  string workbook_rid = 2;
  // LLM-generated or user-set title
  string title = 3;
  // Creation timestamp
  google.protobuf.Timestamp created_at = 4;
  // Last updated timestamp
  google.protobuf.Timestamp updated_at = 5;
}

// ModelMessage is a discriminated union of user and assistant messages.
// Each message type has its own structure and content.
message ModelMessage {
  // UUID - allows us to restart or resume a conversation from a given message
  string id = 1;
  // Timestamp when the message was created
  google.protobuf.Timestamp created_at = 2;

  oneof kind {
    UserModelMessage user = 3;
    AssistantModelMessage assistant = 4;
  }
}

message Conversation {
  ConversationMetadata metadata = 1;
  repeated ModelMessage messages = 2;
}

// A user message containing text and optional context
message UserModelMessage {
  repeated UserContentPart parts = 1;
}

// An assistant message containing text and reasoning
message AssistantModelMessage {
  repeated AssistantContentPart parts = 1;
}

message UserContentPart {
  oneof part {
    TextPart text = 1;
    ImagePart image = 2;
  }
}

// Content part for assistant messages: can be text or reasoning.
message AssistantContentPart {
  oneof part {
    TextPart text = 1;
    ReasoningPart reasoning = 2;
    ToolActionPart tool_action = 3;
  }
}

// Text part for user or assistant messages.
message TextPart {
  string text = 1;
}

// User-supplied image part.
message ImagePart {
  string s3_uri = 1;
  // The media type of the image (e.g. "image/png", "image/jpeg")
  optional string media_type = 2;
}

// Reasoning part for assistant messages.
message ReasoningPart {
  string reasoning = 1;
}

// Tool action part for assistant messages.
message ToolActionPart {
  string id = 1;
  string tool_action_verb = 2; // "Thought", "Read", "Find", "Look-up", etc.
  optional string tool_target = 3; // "workbook", "channel", "variable", "panel", etc.
}
