feat(api): add conversation archive with vector search (MS22-DB-004, MS22-API-004) (#587)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

apps/api/src/conversation-archive/dto/index.ts

@@ -0,0 +1,3 @@
+export { IngestConversationDto, ConversationMessageDto } from "./ingest-conversation.dto";
+export { SearchConversationDto } from "./search-conversation.dto";
+export { ListConversationsDto } from "./list-conversations.dto";

apps/api/src/conversation-archive/dto/ingest-conversation.dto.ts

@@ -0,0 +1,64 @@
+import {
+  IsString,
+  IsArray,
+  IsOptional,
+  IsDateString,
+  MinLength,
+  MaxLength,
+  IsObject,
+  ValidateNested,
+  ArrayMinSize,
+} from "class-validator";
+import { Type } from "class-transformer";
+
+/**
+ * Represents a single message in a conversation session
+ */
+export class ConversationMessageDto {
+  @IsString()
+  role!: string;
+
+  @IsString()
+  @MinLength(1)
+  content!: string;
+
+  @IsOptional()
+  @IsDateString()
+  timestamp?: string;
+}
+
+/**
+ * DTO for ingesting a conversation session log
+ */
+export class IngestConversationDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(500)
+  sessionId!: string;
+
+  @IsString()
+  @MinLength(1)
+  @MaxLength(500)
+  agentId!: string;
+
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => ConversationMessageDto)
+  messages!: ConversationMessageDto[];
+
+  @IsString()
+  @MinLength(1)
+  summary!: string;
+
+  @IsDateString()
+  startedAt!: string;
+
+  @IsOptional()
+  @IsDateString()
+  endedAt?: string;
+
+  @IsOptional()
+  @IsObject()
+  metadata?: Record<string, unknown>;
+}

apps/api/src/conversation-archive/dto/list-conversations.dto.ts

@@ -0,0 +1,33 @@
+import { IsString, IsOptional, MaxLength, IsInt, Min, Max, IsDateString } from "class-validator";
+import { Type } from "class-transformer";
+
+/**
+ * DTO for listing/filtering conversation archives
+ */
+export class ListConversationsDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  agentId?: string;
+
+  @IsOptional()
+  @IsDateString()
+  startedAfter?: string;
+
+  @IsOptional()
+  @IsDateString()
+  startedBefore?: string;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number;
+}

apps/api/src/conversation-archive/dto/search-conversation.dto.ts

@@ -0,0 +1,40 @@
+import {
+  IsString,
+  IsOptional,
+  MinLength,
+  MaxLength,
+  IsInt,
+  Min,
+  Max,
+  IsNumber,
+} from "class-validator";
+import { Type } from "class-transformer";
+
+/**
+ * DTO for semantic search across conversation archives
+ */
+export class SearchConversationDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(1000)
+  query!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  agentId?: string;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsNumber()
+  @Min(0)
+  @Max(1)
+  similarityThreshold?: number;
+}