Sub-Session Splitting

SubSessionId {
  value: string (UUID, unique per sub-session across a user)
}

SessionContext {
  source_session_id: string (original recording session)
  current_sub_session_id: string (active sub-session ID)
}

WindowTranscript {
  text: string (30-second window transcript)
  duration_seconds: int (window length, typically 30)
  window_index: int (sequence number in session)
  start_time: timestamp (window start time)
}

WindowCaption {
  text: string (visual caption from GPU worker)
  entities: [string] (named entities extracted from vision)
  objects: [string] (detected objects/scenes)
}

SubSessionWindow {
  segment_id: string (WorldMMSegment primary key)
  transcript: WindowTranscript (transcription data)
  caption: WindowCaption (visual/caption data)
}

ContinuationDecision {
  continue: boolean (true = same topic, false = new topic)
  reasoning: string (explanation of decision)
}

SubSessionMetadata {
  sub_session_id: SubSessionId (reference)
  name: string (user-facing title, e.g., "Breakfast conversation")
  summary: string (optional: short paragraph describing the chunk)
  window_count: int (number of segments in this sub-session)
  start_time: timestamp (earliest segment in chain)
  end_time: timestamp (latest segment in chain)
  created_at: timestamp
}

AssignSubSessionInput {
  segment_id: string (required, the newly completed segment)
  session_id: string (required, the recording session)
  user_id: string (required)
  transcript: WindowTranscript (required)
  caption: WindowCaption (required)
}

AssignSubSessionOutput {
  sub_session_id: SubSessionId (assigned or created)
  is_new_chain: boolean (true if new sub-session was created)
  chain_window_count: int (total windows now in this chain)
}

AssignSubSessionError {
  status: string (one of: "db_error", "claude_error", "validation_error")
  message: string (human-readable error)
}

FeedRequest {
  cursor: int (offset for pagination)
  limit: int (max items per page, capped at 50)
}

MemoryFeedItem {
  id: string (sub_session_id, not source_session_id)
  time: timestamp (earliest window in sub-session)
  type: string (one of: "visual", "audio", "text")
  thumbnail: string (optional presigned S3 URL)
  processing_status: string (one of: "pending", "complete", "failed")
  title: string (optional sub-session title from SubSessionMetadata)
}

FeedResponse {
  memories: [MemoryFeedItem] (paginated results)
  next_cursor: int | null (next offset, or null if no more pages)
}

function assignSubSessionToWindow(segment_id, session_id, user_id, transcript, caption):
  // Step 1: Find the most recently completed segment in this session
  latest_segment = query WorldMMSegment
    where source_session_id = session_id and processing_status = 'complete'
    order by start_time DESC
    limit 1

  if latest_segment is null:
    // First window in session; create new sub-session
    sub_session_id = generate_uuid()
    write SubSessionMetadata(sub_session_id, name="Untitled", window_count=1)
    update WorldMMSegment.sub_session_id = sub_session_id
    return { sub_session_id, is_new_chain: true }

  // Step 2: Fetch all segments in the current chain
  current_chain = query WorldMMSegment
    where sub_session_id = latest_segment.sub_session_id
    order by start_time ASC

  // Step 3: Prepare context for Claude (summarize if chain is long)
  if current_chain.length > 20:
    // Keep only last 10 windows + first 2 for context
    chain_context = current_chain[0:2] + current_chain[-10:]
  else:
    chain_context = current_chain

  // Build prompt
  chain_transcripts = [w.transcript.text for w in chain_context]
  chain_captions = [w.caption.text for w in chain_context]

  prompt = """
    You are an expert at identifying semantic boundaries in conversation and scene changes.

    Current topic chain (most recent segments):
    Transcripts: {chain_transcripts}
    Visuals: {chain_captions}

    New incoming window:
    Transcript: {transcript.text}
    Visual: {caption.text}

    Question: Does this new window CONTINUE the same conversational topic and scene,
    or does it start something MEANINGFULLY DIFFERENT?

    Respond with JSON: {{ "continue": true/false, "reasoning": "..." }}
  """

  // Step 4: Call Claude
  try:
    response = claude_api.messages.create(
      model="claude-3-5-sonnet-20241022",
      max_tokens=200,
      messages=[{ role: "user", content: prompt }]
    )
    decision = parse_json(response.content[0].text)
  catch ClaudeApiError:
    // Fallback: create new sub-session on API failure
    sub_session_id = generate_uuid()
    write SubSessionMetadata(...)
    update WorldMMSegment.sub_session_id = sub_session_id
    return { sub_session_id, is_new_chain: true }

  // Step 5: Assign based on decision
  if decision.continue:
    // Inherit the current chain's sub_session_id
    update WorldMMSegment.sub_session_id = latest_segment.sub_session_id
    update SubSessionMetadata.window_count += 1
    update SubSessionMetadata.end_time = segment_id.start_time
    return {
      sub_session_id: latest_segment.sub_session_id,
      is_new_chain: false,
      chain_window_count: current_chain.length + 1
    }
  else:
    // Create new chain
    sub_session_id = generate_uuid()
    write SubSessionMetadata(sub_session_id, name="Untitled", window_count=1)
    update WorldMMSegment.sub_session_id = sub_session_id
    return { sub_session_id, is_new_chain: true }

function getFeed(user_id, cursor=0, limit=20):
  // Query all segments for user
  segments = query WorldMMSegment
    where user_id = user_id
    order by start_time DESC, id DESC

  // Group by sub_session_id (or source_session_id if sub_session_id is null)
  grouped = {}
  for segment in segments:
    group_key = segment.sub_session_id or segment.source_session_id
    if group_key not in grouped:
      grouped[group_key] = []
    grouped[group_key].append(segment)

  // Sort groups by latest segment's start_time
  sorted_groups = sorted(grouped.items(),
    key=lambda g: max(s.start_time for s in g[1]),
    reverse=True
  )

  // Pagination
  paginated_groups = sorted_groups[cursor : cursor + limit + 1]
  has_next = len(paginated_groups) > limit
  groups_to_return = paginated_groups[:limit]

  // Build response
  memories = []
  for group_id, group_segments in groups_to_return:
    metadata = query SubSessionMetadata where sub_session_id = group_id (if exists)

    memory_item = {
      id: group_id,
      time: min(s.start_time for s in group_segments),
      type: richest_type([s.type for s in group_segments]),
      thumbnail: first_visual_thumbnail(group_segments),
      processing_status: aggregate_status(group_segments),
      title: metadata.name if metadata else "Untitled Memory"
    }
    memories.append(memory_item)

  return {
    memories,
    next_cursor: cursor + limit if has_next else null
  }