Chat Merge Verbose Endpoint

Plan Metadata

• Plan type: plan
• Parent plan: N/A
• Depends on: docs/plans/chat-async-long-polling.md
• Status: documentation

Status semantics: - draft: Plan is being created or updated and is not final. - approved: Plan is approved but not yet applied in code. - documentation: Code currently exists and matches the plan contract.

Update rule: - When an existing plan is edited, set status to draft until re-approved.

System Intent

• What is being built: Merge the separate /memories/chat/verbose Lambda into the /memories/chat Lambda. A single endpoint handles both regular and verbose responses, controlled by an optional verbose boolean request body field. The verbose Lambda, its SAM resources, and chatWithMemoryVerbose.ts are all deleted — chatWithMemory.ts is the only frontend API function.
• Primary consumer(s): Mobile app (main/app) via chatWithMemory.ts only
• Boundary (black-box scope only): Mobile app → API Gateway → single Chat Lambda; verbose Lambda and verbose frontend module deleted

Stage Gate Tracker

• [x] Stage 1 Mermaid approved
• [x] Stage 2 I/O contracts approved
• [x] Stage 3 pseudocode/technical details approved or skipped

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  App["Mobile App | main/app"]:::unchanged
  ChatScreen["chat.tsx | main/app/app/chat.tsx"]:::done
  ChatWithMemory["chatWithMemory.ts | main/app/lib/api/memory/chatWithMemory.ts"]:::done
  ChatPost["POST /memories/chat | main/server/api/memories/chat/app.py"]:::done
  GPU["GPU Worker | main/server/worldmm/gpu_worker/server.py"]:::unchanged
  ReasoningAgent["ReasoningAgent | main/server/worldmm/retrieval/agent.py"]:::unchanged

  App -->|"user message"| ChatScreen
  ChatScreen -->|"chatWithMemory(question, chatId, verbose)"| ChatWithMemory
  ChatWithMemory -->|"POST question + chat_id + verbose"| ChatPost
  ChatPost -->|"retrieval request"| ReasoningAgent
  ReasoningAgent -->|"answer + optional trace"| ChatPost
  ChatPost -->|"HTTP /generate"| GPU
  GPU -->|"answer text"| ChatPost
  ChatPost -->|"answer + chat_id + optional trace"| ChatWithMemory
  ChatWithMemory -->|"answer + optional trace"| ChatScreen

classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
classDef updated fill:#ffe58a,stroke:#666,stroke-width:1px;
classDef done fill:#d3d3d3,stroke:#666,stroke-width:1px;

2. Black-Box Inputs and Outputs

Keep this short. Define types in JSON-style blocks and capture each flow with path-level rows.

Global Types

ChatId {
  value: string (UUID, identifies a conversation session)
}

StandardError {
  status: number (HTTP status)
  code: string (stable machine-readable code)
  message: string (human-readable summary)
}

Trace {
  rounds: list of retrieval round details (existing shape from chatWithMemoryVerbose.ts)
}

Flow: chat

• Test files: main/server/tests/unit/test_memories_chat_app.py
• Core files: main/server/api/memories/chat/app.py

Type Definitions

ChatInput {
  question: string (required, non-empty)
  chat_id: ChatId (optional)
  verbose: boolean (optional, default false)
  Authorization: string (required, Bearer JWT header)
}

ChatOutput {
  answer: string (required)
  chat_id: ChatId (required)
  trace: Trace (present only when verbose=true)
}

Paths

Flow: deleteVerboseLambda

• Test files: N/A
• Core files: main/server/template.yaml

Paths

Flow: frontendUnifiedCall

• Test files: main/app/__tests__/chat-with-memory.test.ts
• Core files: main/app/lib/api/memory/chatWithMemory.ts

Type Definitions

FrontendChatInput {
  question: string
  chat_id: string (optional)
  verbose: boolean (optional, default false)
}

FrontendChatOutput {
  answer: string
  chat_id: string
  trace: Trace (present only when verbose=true)
}

Paths

3. Pseudocode / Technical Details for Critical Flows (Optional)

Flow: chat handler merge pseudocode

1. Parse body: question, chat_id (optional), verbose (optional, default False)
2. Validate JWT → user_id
3. Validate question non-empty
4. Resolve/create chat_id (existing logic)
5. If verbose:
     answer, trace = run_verbose_implementation(question, chat_id)  # moved from chat_verbose/app.py
     return {answer, chat_id, trace}
   Else:
     answer = run_implementation(question, chat_id)  # existing logic
     return {answer, chat_id}

Deletion checklist

- Delete main/server/api/memories/chat_verbose/ directory
- Remove MemoriesChatVerboseFunction from template.yaml
- Remove /memories/chat/verbose route from template.yaml
- Delete main/app/lib/api/memory/chatWithMemoryVerbose.ts
- Move Trace and TraceRound type exports from chatWithMemoryVerbose.ts into chatWithMemory.ts
- Update main/app/components/TraceView.tsx: import Trace/TraceRound from chatWithMemory.ts
- Update main/app/__tests__/trace-view.test.tsx: import Trace from chatWithMemory.ts
- Update main/app/app/chat.tsx: remove chatWithMemoryVerbose import, pass verbose flag to chatWithMemory

Dependency note

If chat-async-long-polling.md is implemented first, the verbose merge must be applied to the enqueue Lambda + worker Lambda pattern, not the synchronous handler. Sequence: implement long-polling plan first, then this merge plan.

4. Handoff to Related Plan Reconciliation

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.