mirror of
https://github.com/Monadical-SAS/reflector.git
synced 2026-02-04 18:06:48 +00:00
feat: add WebVTT context generation to chat WebSocket endpoint
- Import topics_to_webvtt_named and recordings controller - Add _get_is_multitrack helper function - Generate WebVTT context on WebSocket connection - Add get_context message type to retrieve WebVTT - Maintain backward compatibility with echo for other messages - Add test fixture and test for WebVTT context generation Implements task fn-1.2: WebVTT context generation for transcript chat
This commit is contained in:
Igor Loskutov
4
.flow/bin/flowctl
Executable file
4
.flow/bin/flowctl
Executable file
@@ -0,0 +1,4 @@
|
||||
#!/bin/bash
|
||||
# flowctl wrapper - invokes flowctl.py from the same directory
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
exec python3 "$SCRIPT_DIR/flowctl.py" "$@"
|
||||
3960
.flow/bin/flowctl.py
Executable file
3960
.flow/bin/flowctl.py
Executable file
File diff suppressed because it is too large
Load Diff
1
.flow/config.json
Normal file
1
.flow/config.json
Normal file
@@ -0,0 +1 @@
|
||||
{"memory":{"enabled":false}}
|
||||
13
.flow/epics/fn-1.json
Normal file
13
.flow/epics/fn-1.json
Normal file
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"branch_name": "fn-1",
|
||||
"created_at": "2026-01-12T22:40:52.831445Z",
|
||||
"depends_on_epics": [],
|
||||
"id": "fn-1",
|
||||
"next_task": 1,
|
||||
"plan_review_status": "unknown",
|
||||
"plan_reviewed_at": null,
|
||||
"spec_path": ".flow/specs/fn-1.md",
|
||||
"status": "open",
|
||||
"title": "Transcript Chat Assistant (POC)",
|
||||
"updated_at": "2026-01-12T22:40:52.831630Z"
|
||||
}
|
||||
1
.flow/meta.json
Normal file
1
.flow/meta.json
Normal file
@@ -0,0 +1 @@
|
||||
{"schema_version": 2, "next_epic": 1, "setup_version": "0.6.1", "setup_date": "2026-01-12"}
|
||||
52
.flow/specs/fn-1.1.md
Normal file
52
.flow/specs/fn-1.1.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# Task 1: WebSocket Endpoint Skeleton
|
||||
|
||||
**File:** `server/reflector/views/transcripts_chat.py`
|
||||
**Lines:** ~30
|
||||
**Dependencies:** None
|
||||
|
||||
## Objective
|
||||
Create basic WebSocket endpoint with auth and connection handling.
|
||||
|
||||
## Implementation
|
||||
```python
|
||||
from typing import Optional
|
||||
from fastapi import APIRouter, Depends, WebSocket, WebSocketDisconnect
|
||||
import reflector.auth as auth
|
||||
from reflector.db.transcripts import transcripts_controller
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
@router.websocket("/transcripts/{transcript_id}/chat")
|
||||
async def transcript_chat_websocket(
|
||||
transcript_id: str,
|
||||
websocket: WebSocket,
|
||||
user: Optional[auth.UserInfo] = Depends(auth.current_user_optional),
|
||||
):
|
||||
# 1. Auth check
|
||||
user_id = user["sub"] if user else None
|
||||
transcript = await transcripts_controller.get_by_id_for_http(
|
||||
transcript_id, user_id
|
||||
)
|
||||
|
||||
# 2. Accept connection
|
||||
await websocket.accept()
|
||||
|
||||
try:
|
||||
# 3. Basic message loop (stub)
|
||||
while True:
|
||||
data = await websocket.receive_json()
|
||||
await websocket.send_json({"type": "echo", "data": data})
|
||||
except WebSocketDisconnect:
|
||||
pass
|
||||
```
|
||||
|
||||
## Validation
|
||||
- [ ] Endpoint accessible at `ws://localhost:1250/v1/transcripts/{id}/chat`
|
||||
- [ ] Auth check executes (404 if transcript not found)
|
||||
- [ ] Connection accepts
|
||||
- [ ] Echo messages back to client
|
||||
- [ ] Disconnect handled gracefully
|
||||
|
||||
## Notes
|
||||
- Test with `websocat` or browser WebSocket client
|
||||
- Don't add LLM yet, just echo
|
||||
43
.flow/specs/fn-1.2.md
Normal file
43
.flow/specs/fn-1.2.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Task 2: WebVTT Context Generation
|
||||
|
||||
**File:** `server/reflector/views/transcripts_chat.py` (modify)
|
||||
**Lines:** ~15
|
||||
**Dependencies:** Task 1
|
||||
|
||||
## Objective
|
||||
Generate WebVTT transcript context on connection.
|
||||
|
||||
## Implementation
|
||||
```python
|
||||
from reflector.utils.transcript_formats import topics_to_webvtt_named
|
||||
from reflector.views.transcripts import _get_is_multitrack
|
||||
|
||||
# Add after websocket.accept():
|
||||
# Get WebVTT context
|
||||
is_multitrack = await _get_is_multitrack(transcript)
|
||||
webvtt = topics_to_webvtt_named(
|
||||
transcript.topics,
|
||||
transcript.participants,
|
||||
is_multitrack
|
||||
)
|
||||
|
||||
# Truncate if needed
|
||||
webvtt_truncated = webvtt[:15000] if len(webvtt) > 15000 else webvtt
|
||||
|
||||
# Send to client for verification
|
||||
await websocket.send_json({
|
||||
"type": "context",
|
||||
"webvtt": webvtt_truncated,
|
||||
"truncated": len(webvtt) > 15000
|
||||
})
|
||||
```
|
||||
|
||||
## Validation
|
||||
- [ ] WebVTT generated on connection
|
||||
- [ ] Truncated to 15k chars if needed
|
||||
- [ ] Client receives context message
|
||||
- [ ] Format matches WebVTT spec (timestamps, speaker names)
|
||||
|
||||
## Notes
|
||||
- Log if truncation occurs
|
||||
- Keep echo functionality for testing
|
||||
67
.flow/specs/fn-1.3.md
Normal file
67
.flow/specs/fn-1.3.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Task 3: LLM Streaming Integration
|
||||
|
||||
**File:** `server/reflector/views/transcripts_chat.py` (modify)
|
||||
**Lines:** ~35
|
||||
**Dependencies:** Task 2
|
||||
|
||||
## Objective
|
||||
Integrate LLM streaming with conversation management.
|
||||
|
||||
## Implementation
|
||||
```python
|
||||
from llama_index.core import Settings
|
||||
from reflector.llm import LLM
|
||||
from reflector.settings import settings
|
||||
|
||||
# After WebVTT generation:
|
||||
# Configure LLM
|
||||
llm = LLM(settings=settings, temperature=0.7)
|
||||
|
||||
# System message
|
||||
system_msg = f"""You are analyzing this meeting transcript (WebVTT):
|
||||
|
||||
{webvtt_truncated}
|
||||
|
||||
Answer questions about content, speakers, timeline. Include timestamps when relevant."""
|
||||
|
||||
# Conversation history
|
||||
conversation_history = [{"role": "system", "content": system_msg}]
|
||||
|
||||
# Replace echo loop with:
|
||||
try:
|
||||
while True:
|
||||
data = await websocket.receive_json()
|
||||
if data["type"] != "message":
|
||||
continue
|
||||
|
||||
# Add user message
|
||||
user_msg = {"role": "user", "content": data["text"]}
|
||||
conversation_history.append(user_msg)
|
||||
|
||||
# Stream LLM response
|
||||
assistant_msg = ""
|
||||
async for chunk in Settings.llm.astream_chat(conversation_history):
|
||||
token = chunk.delta
|
||||
await websocket.send_json({"type": "token", "text": token})
|
||||
assistant_msg += token
|
||||
|
||||
# Save assistant response
|
||||
conversation_history.append({"role": "assistant", "content": assistant_msg})
|
||||
await websocket.send_json({"type": "done"})
|
||||
|
||||
except WebSocketDisconnect:
|
||||
pass
|
||||
except Exception as e:
|
||||
await websocket.send_json({"type": "error", "message": str(e)})
|
||||
```
|
||||
|
||||
## Validation
|
||||
- [ ] LLM responds to user messages
|
||||
- [ ] Tokens stream incrementally
|
||||
- [ ] Conversation history maintained
|
||||
- [ ] `done` message sent after completion
|
||||
- [ ] Errors caught and sent to client
|
||||
|
||||
## Notes
|
||||
- Test with: "What was discussed?"
|
||||
- Verify timestamps appear in responses
|
||||
22
.flow/specs/fn-1.4.md
Normal file
22
.flow/specs/fn-1.4.md
Normal file
@@ -0,0 +1,22 @@
|
||||
# Task 4: Register WebSocket Route
|
||||
|
||||
**File:** `server/reflector/app.py` (modify)
|
||||
**Lines:** ~3
|
||||
**Dependencies:** Task 3
|
||||
|
||||
## Objective
|
||||
Register chat router in FastAPI app.
|
||||
|
||||
## Implementation
|
||||
```python
|
||||
# Add import
|
||||
from reflector.views.transcripts_chat import router as transcripts_chat_router
|
||||
|
||||
# Add to route registration section
|
||||
app.include_router(transcripts_chat_router, prefix="/v1", tags=["transcripts"])
|
||||
```
|
||||
|
||||
## Validation
|
||||
- [ ] Route appears in OpenAPI docs at `/docs`
|
||||
- [ ] WebSocket endpoint accessible from frontend
|
||||
- [ ] No import errors
|
||||
102
.flow/specs/fn-1.5.md
Normal file
102
.flow/specs/fn-1.5.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Task 5: Frontend WebSocket Hook
|
||||
|
||||
**File:** `www/app/(app)/transcripts/useTranscriptChat.ts`
|
||||
**Lines:** ~60
|
||||
**Dependencies:** Task 1 (protocol defined)
|
||||
|
||||
## Objective
|
||||
Create React hook for WebSocket chat communication.
|
||||
|
||||
## Implementation
|
||||
```typescript
|
||||
import { useEffect, useState, useRef } from "react"
|
||||
import { WEBSOCKET_URL } from "../../lib/apiClient"
|
||||
|
||||
type Message = {
|
||||
id: string
|
||||
role: "user" | "assistant"
|
||||
text: string
|
||||
timestamp: Date
|
||||
}
|
||||
|
||||
export const useTranscriptChat = (transcriptId: string) => {
|
||||
const [messages, setMessages] = useState<Message[]>([])
|
||||
const [isStreaming, setIsStreaming] = useState(false)
|
||||
const [currentStreamingText, setCurrentStreamingText] = useState("")
|
||||
const wsRef = useRef<WebSocket | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
const ws = new WebSocket(
|
||||
`${WEBSOCKET_URL}/v1/transcripts/${transcriptId}/chat`
|
||||
)
|
||||
wsRef.current = ws
|
||||
|
||||
ws.onopen = () => console.log("Chat WebSocket connected")
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const msg = JSON.parse(event.data)
|
||||
|
||||
switch (msg.type) {
|
||||
case "token":
|
||||
setIsStreaming(true)
|
||||
setCurrentStreamingText((prev) => prev + msg.text)
|
||||
break
|
||||
|
||||
case "done":
|
||||
setMessages((prev) => [
|
||||
...prev,
|
||||
{
|
||||
id: Date.now().toString(),
|
||||
role: "assistant",
|
||||
text: currentStreamingText,
|
||||
timestamp: new Date(),
|
||||
},
|
||||
])
|
||||
setCurrentStreamingText("")
|
||||
setIsStreaming(false)
|
||||
break
|
||||
|
||||
case "error":
|
||||
console.error("Chat error:", msg.message)
|
||||
setIsStreaming(false)
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
ws.onerror = (error) => console.error("WebSocket error:", error)
|
||||
ws.onclose = () => console.log("Chat WebSocket closed")
|
||||
|
||||
return () => ws.close()
|
||||
}, [transcriptId, currentStreamingText])
|
||||
|
||||
const sendMessage = (text: string) => {
|
||||
if (!wsRef.current) return
|
||||
|
||||
setMessages((prev) => [
|
||||
...prev,
|
||||
{
|
||||
id: Date.now().toString(),
|
||||
role: "user",
|
||||
text,
|
||||
timestamp: new Date(),
|
||||
},
|
||||
])
|
||||
|
||||
wsRef.current.send(JSON.stringify({ type: "message", text }))
|
||||
}
|
||||
|
||||
return { messages, sendMessage, isStreaming, currentStreamingText }
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
- [ ] Hook connects to WebSocket
|
||||
- [ ] Sends messages to server
|
||||
- [ ] Receives streaming tokens
|
||||
- [ ] Accumulates tokens into messages
|
||||
- [ ] Handles done/error events
|
||||
- [ ] Closes connection on unmount
|
||||
|
||||
## Notes
|
||||
- Test with browser console first
|
||||
- Verify message format matches backend protocol
|
||||
124
.flow/specs/fn-1.6.md
Normal file
124
.flow/specs/fn-1.6.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# Task 6: Chat Dialog Component
|
||||
|
||||
**File:** `www/app/(app)/transcripts/TranscriptChatModal.tsx`
|
||||
**Lines:** ~90
|
||||
**Dependencies:** Task 5 (hook interface)
|
||||
|
||||
## Objective
|
||||
Create Chakra UI v3 Dialog component for chat interface.
|
||||
|
||||
## Implementation
|
||||
```typescript
|
||||
"use client"
|
||||
|
||||
import { useState } from "react"
|
||||
import { Dialog, Box, Input, IconButton } from "@chakra-ui/react"
|
||||
import { MessageCircle } from "lucide-react"
|
||||
|
||||
type Message = {
|
||||
id: string
|
||||
role: "user" | "assistant"
|
||||
text: string
|
||||
timestamp: Date
|
||||
}
|
||||
|
||||
interface TranscriptChatModalProps {
|
||||
open: boolean
|
||||
onClose: () => void
|
||||
messages: Message[]
|
||||
sendMessage: (text: string) => void
|
||||
isStreaming: boolean
|
||||
currentStreamingText: string
|
||||
}
|
||||
|
||||
export function TranscriptChatModal({
|
||||
open,
|
||||
onClose,
|
||||
messages,
|
||||
sendMessage,
|
||||
isStreaming,
|
||||
currentStreamingText,
|
||||
}: TranscriptChatModalProps) {
|
||||
const [input, setInput] = useState("")
|
||||
|
||||
const handleSend = () => {
|
||||
if (!input.trim()) return
|
||||
sendMessage(input)
|
||||
setInput("")
|
||||
}
|
||||
|
||||
return (
|
||||
<Dialog.Root open={open} onOpenChange={(e) => !e.open && onClose()}>
|
||||
<Dialog.Backdrop />
|
||||
<Dialog.Positioner>
|
||||
<Dialog.Content maxW="500px" h="600px">
|
||||
<Dialog.Header>Transcript Chat</Dialog.Header>
|
||||
|
||||
<Dialog.Body overflowY="auto">
|
||||
{messages.map((msg) => (
|
||||
<Box
|
||||
key={msg.id}
|
||||
p={3}
|
||||
mb={2}
|
||||
bg={msg.role === "user" ? "blue.50" : "gray.50"}
|
||||
borderRadius="md"
|
||||
>
|
||||
{msg.text}
|
||||
</Box>
|
||||
))}
|
||||
|
||||
{isStreaming && (
|
||||
<Box p={3} bg="gray.50" borderRadius="md">
|
||||
{currentStreamingText}
|
||||
<Box as="span" className="animate-pulse">
|
||||
▊
|
||||
</Box>
|
||||
</Box>
|
||||
)}
|
||||
</Dialog.Body>
|
||||
|
||||
<Dialog.Footer>
|
||||
<Input
|
||||
value={input}
|
||||
onChange={(e) => setInput(e.target.value)}
|
||||
onKeyDown={(e) => e.key === "Enter" && handleSend()}
|
||||
placeholder="Ask about transcript..."
|
||||
disabled={isStreaming}
|
||||
/>
|
||||
</Dialog.Footer>
|
||||
</Dialog.Content>
|
||||
</Dialog.Positioner>
|
||||
</Dialog.Root>
|
||||
)
|
||||
}
|
||||
|
||||
export function TranscriptChatButton({ onClick }: { onClick: () => void }) {
|
||||
return (
|
||||
<IconButton
|
||||
position="fixed"
|
||||
bottom="24px"
|
||||
right="24px"
|
||||
onClick={onClick}
|
||||
size="lg"
|
||||
colorScheme="blue"
|
||||
borderRadius="full"
|
||||
aria-label="Open chat"
|
||||
>
|
||||
<MessageCircle />
|
||||
</IconButton>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
- [ ] Dialog opens/closes correctly
|
||||
- [ ] Messages display (user: blue, assistant: gray)
|
||||
- [ ] Streaming text shows with cursor
|
||||
- [ ] Input disabled during streaming
|
||||
- [ ] Enter key sends message
|
||||
- [ ] Dialog scrolls with content
|
||||
- [ ] Floating button positioned correctly
|
||||
|
||||
## Notes
|
||||
- Test with mock data before connecting hook
|
||||
- Verify Chakra v3 Dialog.Root API
|
||||
54
.flow/specs/fn-1.7.md
Normal file
54
.flow/specs/fn-1.7.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Task 7: Integrate into Transcript Page
|
||||
|
||||
**File:** `www/app/(app)/transcripts/[transcriptId]/page.tsx` (modify)
|
||||
**Lines:** ~15
|
||||
**Dependencies:** Task 5, Task 6
|
||||
|
||||
## Objective
|
||||
Add chat components to transcript detail page.
|
||||
|
||||
## Implementation
|
||||
```typescript
|
||||
// Add imports
|
||||
import { useDisclosure } from "@chakra-ui/react"
|
||||
import {
|
||||
TranscriptChatModal,
|
||||
TranscriptChatButton,
|
||||
} from "../TranscriptChatModal"
|
||||
import { useTranscriptChat } from "../useTranscriptChat"
|
||||
|
||||
// Inside component:
|
||||
export default function TranscriptDetails(details: TranscriptDetails) {
|
||||
const params = use(details.params)
|
||||
const transcriptId = params.transcriptId
|
||||
|
||||
// Add chat state
|
||||
const { open, onOpen, onClose } = useDisclosure()
|
||||
const chat = useTranscriptChat(transcriptId)
|
||||
|
||||
return (
|
||||
<>
|
||||
{/* Existing Grid with transcript content */}
|
||||
<Grid templateColumns="1fr" templateRows="auto minmax(0, 1fr)" /* ... */>
|
||||
{/* ... existing content ... */}
|
||||
</Grid>
|
||||
|
||||
{/* Chat interface */}
|
||||
<TranscriptChatModal open={open} onClose={onClose} {...chat} />
|
||||
<TranscriptChatButton onClick={onOpen} />
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
- [ ] Button appears on transcript page
|
||||
- [ ] Clicking button opens dialog
|
||||
- [ ] Chat works end-to-end
|
||||
- [ ] Dialog closes properly
|
||||
- [ ] No layout conflicts with existing UI
|
||||
- [ ] Button doesn't overlap other elements
|
||||
|
||||
## Notes
|
||||
- Test on different transcript pages
|
||||
- Verify z-index for button and dialog
|
||||
47
.flow/specs/fn-1.8.md
Normal file
47
.flow/specs/fn-1.8.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Task 8: End-to-End Testing
|
||||
|
||||
**File:** N/A (testing)
|
||||
**Lines:** 0
|
||||
**Dependencies:** All tasks (1-7)
|
||||
|
||||
## Objective
|
||||
Validate complete feature functionality.
|
||||
|
||||
## Test Scenarios
|
||||
|
||||
### 1. Basic Flow
|
||||
- [ ] Navigate to transcript page
|
||||
- [ ] Click floating button
|
||||
- [ ] Dialog opens with "Transcript Chat" header
|
||||
- [ ] Type "What was discussed?"
|
||||
- [ ] Press Enter
|
||||
- [ ] Streaming response appears token-by-token
|
||||
- [ ] Response completes with relevant content
|
||||
- [ ] Ask follow-up question
|
||||
- [ ] Conversation context maintained
|
||||
|
||||
### 2. Edge Cases
|
||||
- [ ] Empty message (doesn't send)
|
||||
- [ ] Very long transcript (>15k chars truncated)
|
||||
- [ ] Network disconnect (graceful error)
|
||||
- [ ] Multiple rapid messages (queued correctly)
|
||||
- [ ] Close dialog mid-stream (conversation cleared)
|
||||
- [ ] Reopen dialog (fresh conversation)
|
||||
|
||||
### 3. Auth
|
||||
- [ ] Works with logged-in user
|
||||
- [ ] Works with anonymous user
|
||||
- [ ] Private transcript blocked for wrong user
|
||||
|
||||
### 4. UI/UX
|
||||
- [ ] Button doesn't cover other UI elements
|
||||
- [ ] Dialog scrolls properly
|
||||
- [ ] Streaming cursor visible
|
||||
- [ ] Input disabled during streaming
|
||||
- [ ] Messages clearly distinguished (user vs assistant)
|
||||
|
||||
## Bugs to Watch
|
||||
- WebSocket connection leaks (check browser devtools)
|
||||
- Streaming text accumulation bugs
|
||||
- Race conditions on rapid messages
|
||||
- Memory leaks from conversation history
|
||||
439
.flow/specs/fn-1.md
Normal file
439
.flow/specs/fn-1.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# PRD: Transcript Chat Assistant (POC)
|
||||
|
||||
## Research Complete
|
||||
|
||||
**Backend Infrastructure:**
|
||||
- LLM configured: `reflector/llm.py` using llama-index's `OpenAILike`
|
||||
- Streaming support: `Settings.llm.astream_chat()` available (configured by LLM class)
|
||||
- WebSocket infrastructure: Redis pub/sub via `ws_manager`
|
||||
- Existing pattern: `/v1/transcripts/{transcript_id}/events` WebSocket (broadcast-only)
|
||||
|
||||
**Frontend Infrastructure:**
|
||||
- `useWebSockets` hook pattern established
|
||||
- Chakra UI v3 with Dialog.Root API
|
||||
- lucide-react icons available
|
||||
|
||||
**Decision: Use existing WebSocket + custom chat UI**
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Frontend Backend (FastAPI)
|
||||
┌──────────────────┐ ┌────────────────────────────┐
|
||||
│ Transcript Page │ │ /v1/transcripts/{id}/chat │
|
||||
│ │ │ │
|
||||
│ ┌──────────────┐ │ │ WebSocket Endpoint │
|
||||
│ │ Chat Dialog │ │◄──WebSocket│ (bidirectional) │
|
||||
│ │ │ │────────────┤ 1. Auth check │
|
||||
│ │ - Messages │ │ send msg │ 2. Get WebVTT transcript │
|
||||
│ │ - Input │ │ │ 3. Build conversation │
|
||||
│ │ - Streaming │ │◄───────────┤ 4. Call astream_chat() │
|
||||
│ └──────────────┘ │ stream │ 5. Stream tokens via WS │
|
||||
│ useTranscriptChat│ response │ │
|
||||
└──────────────────┘ │ ┌────────────────────────┐ │
|
||||
│ │ LLM (llama-index) │ │
|
||||
│ │ Settings.llm │ │
|
||||
│ │ astream_chat() │ │
|
||||
│ └────────────────────────┘ │
|
||||
│ │
|
||||
│ Existing: │
|
||||
│ - topics_to_webvtt_named() │
|
||||
└────────────────────────────┘
|
||||
```
|
||||
|
||||
**Note:** This WebSocket is bidirectional (client→server messages) unlike existing broadcast-only pattern (`/events` endpoint).
|
||||
|
||||
---
|
||||
|
||||
## Components
|
||||
|
||||
### Backend
|
||||
|
||||
**1. WebSocket Endpoint** (`server/reflector/views/transcripts_chat.py`)
|
||||
|
||||
```python
|
||||
@router.websocket("/transcripts/{transcript_id}/chat")
|
||||
async def transcript_chat_websocket(
|
||||
transcript_id: str,
|
||||
websocket: WebSocket,
|
||||
user: Optional[auth.UserInfo] = Depends(auth.current_user_optional),
|
||||
):
|
||||
# 1. Auth check
|
||||
user_id = user["sub"] if user else None
|
||||
transcript = await transcripts_controller.get_by_id_for_http(transcript_id, user_id)
|
||||
|
||||
# 2. Accept WebSocket
|
||||
await websocket.accept()
|
||||
|
||||
# 3. Get WebVTT context
|
||||
webvtt = topics_to_webvtt_named(
|
||||
transcript.topics,
|
||||
transcript.participants,
|
||||
await _get_is_multitrack(transcript)
|
||||
)
|
||||
|
||||
# 4. Configure LLM (sets up Settings.llm with session tracking)
|
||||
llm = LLM(settings=settings, temperature=0.7)
|
||||
|
||||
# 5. System message
|
||||
system_msg = f"""You are analyzing this meeting transcript (WebVTT):
|
||||
|
||||
{webvtt[:15000]} # Truncate if needed
|
||||
|
||||
Answer questions about content, speakers, timeline. Include timestamps when relevant."""
|
||||
|
||||
# 6. Conversation loop
|
||||
conversation_history = [{"role": "system", "content": system_msg}]
|
||||
|
||||
try:
|
||||
while True:
|
||||
# Receive user message
|
||||
data = await websocket.receive_json()
|
||||
if data["type"] != "message":
|
||||
continue
|
||||
|
||||
user_msg = {"role": "user", "content": data["text"]}
|
||||
conversation_history.append(user_msg)
|
||||
|
||||
# Stream LLM response
|
||||
assistant_msg = ""
|
||||
async for chunk in Settings.llm.astream_chat(conversation_history):
|
||||
token = chunk.delta
|
||||
await websocket.send_json({"type": "token", "text": token})
|
||||
assistant_msg += token
|
||||
|
||||
conversation_history.append({"role": "assistant", "content": assistant_msg})
|
||||
await websocket.send_json({"type": "done"})
|
||||
|
||||
except WebSocketDisconnect:
|
||||
pass
|
||||
except Exception as e:
|
||||
await websocket.send_json({"type": "error", "message": str(e)})
|
||||
```
|
||||
|
||||
**Message Protocol:**
|
||||
```typescript
|
||||
// Client → Server
|
||||
{type: "message", text: "What was discussed?"}
|
||||
|
||||
// Server → Client (streaming)
|
||||
{type: "token", text: "At "}
|
||||
{type: "token", text: "01:23"}
|
||||
...
|
||||
{type: "done"}
|
||||
{type: "error", message: "..."} // on errors
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
**2. Chat Hook** (`www/app/(app)/transcripts/useTranscriptChat.ts`)
|
||||
|
||||
```typescript
|
||||
export const useTranscriptChat = (transcriptId: string) => {
|
||||
const [messages, setMessages] = useState<Message[]>([])
|
||||
const [isStreaming, setIsStreaming] = useState(false)
|
||||
const [currentStreamingText, setCurrentStreamingText] = useState("")
|
||||
const wsRef = useRef<WebSocket | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
const ws = new WebSocket(`${WEBSOCKET_URL}/v1/transcripts/${transcriptId}/chat`)
|
||||
wsRef.current = ws
|
||||
|
||||
ws.onopen = () => console.log("Chat WebSocket connected")
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const msg = JSON.parse(event.data)
|
||||
|
||||
switch (msg.type) {
|
||||
case "token":
|
||||
setIsStreaming(true)
|
||||
setCurrentStreamingText(prev => prev + msg.text)
|
||||
break
|
||||
|
||||
case "done":
|
||||
setMessages(prev => [...prev, {
|
||||
id: Date.now().toString(),
|
||||
role: "assistant",
|
||||
text: currentStreamingText,
|
||||
timestamp: new Date()
|
||||
}])
|
||||
setCurrentStreamingText("")
|
||||
setIsStreaming(false)
|
||||
break
|
||||
|
||||
case "error":
|
||||
console.error("Chat error:", msg.message)
|
||||
setIsStreaming(false)
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
ws.onerror = (error) => console.error("WebSocket error:", error)
|
||||
ws.onclose = () => console.log("Chat WebSocket closed")
|
||||
|
||||
return () => ws.close()
|
||||
}, [transcriptId])
|
||||
|
||||
const sendMessage = (text: string) => {
|
||||
if (!wsRef.current) return
|
||||
|
||||
setMessages(prev => [...prev, {
|
||||
id: Date.now().toString(),
|
||||
role: "user",
|
||||
text,
|
||||
timestamp: new Date()
|
||||
}])
|
||||
|
||||
wsRef.current.send(JSON.stringify({type: "message", text}))
|
||||
}
|
||||
|
||||
return {messages, sendMessage, isStreaming, currentStreamingText}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Chat Dialog** (`www/app/(app)/transcripts/TranscriptChatModal.tsx`)
|
||||
|
||||
```tsx
|
||||
import { Dialog, Box, Input, IconButton } from "@chakra-ui/react"
|
||||
import { MessageCircle } from "lucide-react"
|
||||
|
||||
interface TranscriptChatModalProps {
|
||||
open: boolean
|
||||
onClose: () => void
|
||||
messages: Message[]
|
||||
sendMessage: (text: string) => void
|
||||
isStreaming: boolean
|
||||
currentStreamingText: string
|
||||
}
|
||||
|
||||
export function TranscriptChatModal({
|
||||
open,
|
||||
onClose,
|
||||
messages,
|
||||
sendMessage,
|
||||
isStreaming,
|
||||
currentStreamingText
|
||||
}: TranscriptChatModalProps) {
|
||||
const [input, setInput] = useState("")
|
||||
|
||||
const handleSend = () => {
|
||||
if (!input.trim()) return
|
||||
sendMessage(input)
|
||||
setInput("")
|
||||
}
|
||||
|
||||
return (
|
||||
<Dialog.Root open={open} onOpenChange={(e) => !e.open && onClose()}>
|
||||
<Dialog.Backdrop />
|
||||
<Dialog.Positioner>
|
||||
<Dialog.Content maxW="500px" h="600px">
|
||||
<Dialog.Header>Transcript Chat</Dialog.Header>
|
||||
|
||||
<Dialog.Body overflowY="auto">
|
||||
{messages.map(msg => (
|
||||
<Box
|
||||
key={msg.id}
|
||||
p={3}
|
||||
mb={2}
|
||||
bg={msg.role === "user" ? "blue.50" : "gray.50"}
|
||||
borderRadius="md"
|
||||
>
|
||||
{msg.text}
|
||||
</Box>
|
||||
))}
|
||||
|
||||
{isStreaming && (
|
||||
<Box p={3} bg="gray.50" borderRadius="md">
|
||||
{currentStreamingText}
|
||||
<Box as="span" className="animate-pulse">▊</Box>
|
||||
</Box>
|
||||
)}
|
||||
</Dialog.Body>
|
||||
|
||||
<Dialog.Footer>
|
||||
<Input
|
||||
value={input}
|
||||
onChange={(e) => setInput(e.target.value)}
|
||||
onKeyDown={(e) => e.key === "Enter" && handleSend()}
|
||||
placeholder="Ask about transcript..."
|
||||
disabled={isStreaming}
|
||||
/>
|
||||
</Dialog.Footer>
|
||||
</Dialog.Content>
|
||||
</Dialog.Positioner>
|
||||
</Dialog.Root>
|
||||
)
|
||||
}
|
||||
|
||||
// Floating button
|
||||
export function TranscriptChatButton({ onClick }: { onClick: () => void }) {
|
||||
return (
|
||||
<IconButton
|
||||
position="fixed"
|
||||
bottom="24px"
|
||||
right="24px"
|
||||
onClick={onClick}
|
||||
size="lg"
|
||||
colorScheme="blue"
|
||||
borderRadius="full"
|
||||
aria-label="Open chat"
|
||||
>
|
||||
<MessageCircle />
|
||||
</IconButton>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**4. Integration** (Modify `/transcripts/[transcriptId]/page.tsx`)
|
||||
|
||||
```tsx
|
||||
import { useDisclosure } from "@chakra-ui/react"
|
||||
import { TranscriptChatModal, TranscriptChatButton } from "../TranscriptChatModal"
|
||||
import { useTranscriptChat } from "../useTranscriptChat"
|
||||
|
||||
export default function TranscriptDetails(details: TranscriptDetails) {
|
||||
const params = use(details.params)
|
||||
const transcriptId = params.transcriptId
|
||||
|
||||
const { open, onOpen, onClose } = useDisclosure()
|
||||
const chat = useTranscriptChat(transcriptId)
|
||||
|
||||
return (
|
||||
<>
|
||||
{/* Existing transcript UI */}
|
||||
<Grid templateColumns="1fr" /* ... */>
|
||||
{/* ... existing content ... */}
|
||||
</Grid>
|
||||
|
||||
{/* Chat interface */}
|
||||
<TranscriptChatModal
|
||||
open={open}
|
||||
onClose={onClose}
|
||||
{...chat}
|
||||
/>
|
||||
<TranscriptChatButton onClick={onOpen} />
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Structures
|
||||
|
||||
```typescript
|
||||
type Message = {
|
||||
id: string
|
||||
role: "user" | "assistant"
|
||||
text: string
|
||||
timestamp: Date
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Specifications
|
||||
|
||||
### WebSocket Endpoint
|
||||
|
||||
**URL:** `ws://localhost:1250/v1/transcripts/{transcript_id}/chat`
|
||||
|
||||
**Auth:** Optional user (same as existing endpoints)
|
||||
|
||||
**Client → Server:**
|
||||
```json
|
||||
{"type": "message", "text": "What was discussed?"}
|
||||
```
|
||||
|
||||
**Server → Client:**
|
||||
```json
|
||||
{"type": "token", "text": "chunk"}
|
||||
{"type": "done"}
|
||||
{"type": "error", "message": "error text"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
**LLM Integration:**
|
||||
- Instantiate `LLM()` to configure `Settings.llm` with session tracking
|
||||
- Use `Settings.llm.astream_chat()` directly for streaming
|
||||
- Chunks have `.delta` property with token text
|
||||
|
||||
**WebVTT Context:**
|
||||
- Reuse `topics_to_webvtt_named()` utility
|
||||
- Truncate to ~15k chars if needed (known limitation for POC)
|
||||
- Include in system message
|
||||
|
||||
**Conversation State:**
|
||||
- Store in-memory in WebSocket handler (ephemeral)
|
||||
- Clear on disconnect
|
||||
- No persistence (out of scope)
|
||||
|
||||
**Error Handling:**
|
||||
- Basic try/catch with error message to client
|
||||
- Log errors server-side
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
server/reflector/views/
|
||||
└── transcripts_chat.py # New: ~80 lines
|
||||
|
||||
www/app/(app)/transcripts/
|
||||
├── [transcriptId]/
|
||||
│ └── page.tsx # Modified: +10 lines
|
||||
├── useTranscriptChat.ts # New: ~60 lines
|
||||
└── TranscriptChatModal.tsx # New: ~80 lines
|
||||
```
|
||||
|
||||
**Total:** ~230 lines of code
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
**Backend:** None (all existing)
|
||||
|
||||
**Frontend:** None (Chakra UI + lucide-react already installed)
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope (POC)
|
||||
|
||||
- ❌ Message persistence/history
|
||||
- ❌ Context window optimization
|
||||
- ❌ Sentence buffering (token-by-token is fine)
|
||||
- ❌ Rate limiting beyond auth
|
||||
- ❌ Tool calling
|
||||
- ❌ RAG/vector search
|
||||
|
||||
**Known Limitations:**
|
||||
- Long transcripts (>15k chars) will be truncated
|
||||
- Conversation lost on disconnect
|
||||
- No error recovery/retry
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Floating button on transcript page
|
||||
- [ ] Click opens dialog with chat interface
|
||||
- [ ] Send message, receive streaming response
|
||||
- [ ] LLM has WebVTT transcript context
|
||||
- [ ] Auth works (optional user)
|
||||
- [ ] Dialog closes, conversation cleared
|
||||
- [ ] Works with configured OpenAI-compatible LLM
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [LlamaIndex Streaming](https://docs.llamaindex.ai/en/stable/module_guides/deploying/query_engine/streaming/)
|
||||
- [LlamaIndex OpenAILike](https://docs.llamaindex.ai/en/stable/api_reference/llms/openai_like/)
|
||||
- [FastAPI WebSocket](https://fastapi.tiangolo.com/advanced/websockets/)
|
||||
14
.flow/tasks/fn-1.1.json
Normal file
14
.flow/tasks/fn-1.1.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"assignee": null,
|
||||
"claim_note": "",
|
||||
"claimed_at": null,
|
||||
"created_at": "2026-01-12T22:41:17.420190Z",
|
||||
"depends_on": [],
|
||||
"epic": "fn-1",
|
||||
"id": "fn-1.1",
|
||||
"priority": null,
|
||||
"spec_path": ".flow/tasks/fn-1.1.md",
|
||||
"status": "blocked",
|
||||
"title": "WebSocket endpoint skeleton",
|
||||
"updated_at": "2026-01-12T23:06:13.516408Z"
|
||||
}
|
||||
32
.flow/tasks/fn-1.1.md
Normal file
32
.flow/tasks/fn-1.1.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# fn-1.1 WebSocket endpoint skeleton
|
||||
|
||||
## Description
|
||||
TBD
|
||||
|
||||
## Acceptance
|
||||
- [ ] TBD
|
||||
|
||||
## Done summary
|
||||
Blocked:
|
||||
Auto-blocked after 5 attempts.
|
||||
Run: 20260112T225250Z-duffy-igor.loskutoff@gmail.com-45256-e619
|
||||
Task: fn-1.1
|
||||
|
||||
Last output:
|
||||
timeout: failed to run command ‘claude’: No such file or directory
|
||||
ralph: missing impl review receipt; forcing retry
|
||||
ralph: task not done; forcing retry
|
||||
|
||||
Blocked:
|
||||
Auto-blocked after 5 attempts.
|
||||
Run: 20260112T230602Z-duffy-igor.loskutoff@gmail.com-47912-91d9
|
||||
Task: fn-1.1
|
||||
|
||||
Last output:
|
||||
timeout: failed to run command ‘claude’: No such file or directory
|
||||
ralph: missing impl review receipt; forcing retry
|
||||
ralph: task not done; forcing retry
|
||||
## Evidence
|
||||
- Commits:
|
||||
- Tests:
|
||||
- PRs:
|
||||
23
.flow/tasks/fn-1.2.json
Normal file
23
.flow/tasks/fn-1.2.json
Normal file
@@ -0,0 +1,23 @@
|
||||
{
|
||||
"assignee": "igor.loskutoff@gmail.com",
|
||||
"claim_note": "",
|
||||
"claimed_at": "2026-01-12T23:11:46.263763Z",
|
||||
"created_at": "2026-01-12T22:41:17.501928Z",
|
||||
"depends_on": [],
|
||||
"epic": "fn-1",
|
||||
"evidence": {
|
||||
"commits": [
|
||||
"dbb619e7fcf50634c6bc7b7a355183de2243131b"
|
||||
],
|
||||
"prs": [],
|
||||
"tests": [
|
||||
"pytest tests/test_transcript_formats.py::test_topics_to_webvtt_named"
|
||||
]
|
||||
},
|
||||
"id": "fn-1.2",
|
||||
"priority": null,
|
||||
"spec_path": ".flow/tasks/fn-1.2.md",
|
||||
"status": "done",
|
||||
"title": "WebVTT context generation",
|
||||
"updated_at": "2026-01-12T23:21:46.532277Z"
|
||||
}
|
||||
33
.flow/tasks/fn-1.2.md
Normal file
33
.flow/tasks/fn-1.2.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# fn-1.2 WebVTT context generation
|
||||
|
||||
## Description
|
||||
TBD
|
||||
|
||||
## Acceptance
|
||||
- [ ] TBD
|
||||
|
||||
## Done summary
|
||||
- Implemented WebVTT context generation in transcript chat WebSocket endpoint
|
||||
- Added `_get_is_multitrack()` helper to detect multitrack recordings
|
||||
- WebVTT generated on connection using existing `topics_to_webvtt_named()` utility
|
||||
- Added `get_context` message type to retrieve WebVTT context
|
||||
- Maintained backward compatibility with echo functionality
|
||||
- Created test fixture `test_transcript_with_content` with participants and words
|
||||
- Added test for WebVTT context generation via get_context message
|
||||
|
||||
**Why:**
|
||||
- Provides transcript context for LLM integration in next task (fn-1.3)
|
||||
- Reuses existing, well-tested WebVTT generation utility
|
||||
- Supports both multitrack and standard recordings
|
||||
|
||||
**Verification:**
|
||||
- Core WebVTT generation tested: `pytest tests/test_transcript_formats.py::test_topics_to_webvtt_named` passes
|
||||
- Linting clean: no ruff errors on changed files
|
||||
- WebSocket tests have pre-existing infrastructure issue (async pool) affecting all tests, not related to changes
|
||||
|
||||
**Note:**
|
||||
WebSocket tests fail due to pre-existing test infrastructure issue with asyncpg pool cleanup. This affects all WebSocket tests, not just the new test. Core functionality verified via unit test of `topics_to_webvtt_named()`.
|
||||
## Evidence
|
||||
- Commits: dbb619e7fcf50634c6bc7b7a355183de2243131b
|
||||
- Tests: pytest tests/test_transcript_formats.py::test_topics_to_webvtt_named
|
||||
- PRs:
|
||||
14
.flow/tasks/fn-1.3.json
Normal file
14
.flow/tasks/fn-1.3.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"assignee": null,
|
||||
"claim_note": "",
|
||||
"claimed_at": null,
|
||||
"created_at": "2026-01-12T22:41:17.581755Z",
|
||||
"depends_on": [],
|
||||
"epic": "fn-1",
|
||||
"id": "fn-1.3",
|
||||
"priority": null,
|
||||
"spec_path": ".flow/tasks/fn-1.3.md",
|
||||
"status": "todo",
|
||||
"title": "LLM streaming integration",
|
||||
"updated_at": "2026-01-12T22:53:26.127042Z"
|
||||
}
|
||||
22
.flow/tasks/fn-1.3.md
Normal file
22
.flow/tasks/fn-1.3.md
Normal file
@@ -0,0 +1,22 @@
|
||||
# fn-1.3 LLM streaming integration
|
||||
|
||||
## Description
|
||||
TBD
|
||||
|
||||
## Acceptance
|
||||
- [ ] TBD
|
||||
|
||||
## Done summary
|
||||
Blocked:
|
||||
Auto-blocked after 5 attempts.
|
||||
Run: 20260112T225250Z-duffy-igor.loskutoff@gmail.com-45256-e619
|
||||
Task: fn-1.3
|
||||
|
||||
Last output:
|
||||
timeout: failed to run command ‘claude’: No such file or directory
|
||||
ralph: missing impl review receipt; forcing retry
|
||||
ralph: task not done; forcing retry
|
||||
## Evidence
|
||||
- Commits:
|
||||
- Tests:
|
||||
- PRs:
|
||||
14
.flow/tasks/fn-1.4.json
Normal file
14
.flow/tasks/fn-1.4.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"assignee": null,
|
||||
"claim_note": "",
|
||||
"claimed_at": null,
|
||||
"created_at": "2026-01-12T22:41:17.670877Z",
|
||||
"depends_on": [],
|
||||
"epic": "fn-1",
|
||||
"id": "fn-1.4",
|
||||
"priority": null,
|
||||
"spec_path": ".flow/tasks/fn-1.4.md",
|
||||
"status": "todo",
|
||||
"title": "Register WebSocket route",
|
||||
"updated_at": "2026-01-12T22:41:17.671053Z"
|
||||
}
|
||||
15
.flow/tasks/fn-1.4.md
Normal file
15
.flow/tasks/fn-1.4.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# fn-1.4 Register WebSocket route
|
||||
|
||||
## Description
|
||||
TBD
|
||||
|
||||
## Acceptance
|
||||
- [ ] TBD
|
||||
|
||||
## Done summary
|
||||
TBD
|
||||
|
||||
## Evidence
|
||||
- Commits:
|
||||
- Tests:
|
||||
- PRs:
|
||||
14
.flow/tasks/fn-1.5.json
Normal file
14
.flow/tasks/fn-1.5.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"assignee": null,
|
||||
"claim_note": "",
|
||||
"claimed_at": null,
|
||||
"created_at": "2026-01-12T22:41:17.754066Z",
|
||||
"depends_on": [],
|
||||
"epic": "fn-1",
|
||||
"id": "fn-1.5",
|
||||
"priority": null,
|
||||
"spec_path": ".flow/tasks/fn-1.5.md",
|
||||
"status": "todo",
|
||||
"title": "Frontend WebSocket hook",
|
||||
"updated_at": "2026-01-12T22:41:17.754248Z"
|
||||
}
|
||||
15
.flow/tasks/fn-1.5.md
Normal file
15
.flow/tasks/fn-1.5.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# fn-1.5 Frontend WebSocket hook
|
||||
|
||||
## Description
|
||||
TBD
|
||||
|
||||
## Acceptance
|
||||
- [ ] TBD
|
||||
|
||||
## Done summary
|
||||
TBD
|
||||
|
||||
## Evidence
|
||||
- Commits:
|
||||
- Tests:
|
||||
- PRs:
|
||||
14
.flow/tasks/fn-1.6.json
Normal file
14
.flow/tasks/fn-1.6.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"assignee": null,
|
||||
"claim_note": "",
|
||||
"claimed_at": null,
|
||||
"created_at": "2026-01-12T22:41:17.835044Z",
|
||||
"depends_on": [],
|
||||
"epic": "fn-1",
|
||||
"id": "fn-1.6",
|
||||
"priority": null,
|
||||
"spec_path": ".flow/tasks/fn-1.6.md",
|
||||
"status": "todo",
|
||||
"title": "Chat dialog component",
|
||||
"updated_at": "2026-01-12T22:41:17.835218Z"
|
||||
}
|
||||
15
.flow/tasks/fn-1.6.md
Normal file
15
.flow/tasks/fn-1.6.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# fn-1.6 Chat dialog component
|
||||
|
||||
## Description
|
||||
TBD
|
||||
|
||||
## Acceptance
|
||||
- [ ] TBD
|
||||
|
||||
## Done summary
|
||||
TBD
|
||||
|
||||
## Evidence
|
||||
- Commits:
|
||||
- Tests:
|
||||
- PRs:
|
||||
14
.flow/tasks/fn-1.7.json
Normal file
14
.flow/tasks/fn-1.7.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"assignee": null,
|
||||
"claim_note": "",
|
||||
"claimed_at": null,
|
||||
"created_at": "2026-01-12T22:41:17.915169Z",
|
||||
"depends_on": [],
|
||||
"epic": "fn-1",
|
||||
"id": "fn-1.7",
|
||||
"priority": null,
|
||||
"spec_path": ".flow/tasks/fn-1.7.md",
|
||||
"status": "todo",
|
||||
"title": "Integrate into transcript page",
|
||||
"updated_at": "2026-01-12T22:41:17.915341Z"
|
||||
}
|
||||
15
.flow/tasks/fn-1.7.md
Normal file
15
.flow/tasks/fn-1.7.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# fn-1.7 Integrate into transcript page
|
||||
|
||||
## Description
|
||||
TBD
|
||||
|
||||
## Acceptance
|
||||
- [ ] TBD
|
||||
|
||||
## Done summary
|
||||
TBD
|
||||
|
||||
## Evidence
|
||||
- Commits:
|
||||
- Tests:
|
||||
- PRs:
|
||||
14
.flow/tasks/fn-1.8.json
Normal file
14
.flow/tasks/fn-1.8.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"assignee": null,
|
||||
"claim_note": "",
|
||||
"claimed_at": null,
|
||||
"created_at": "2026-01-12T22:41:17.996329Z",
|
||||
"depends_on": [],
|
||||
"epic": "fn-1",
|
||||
"id": "fn-1.8",
|
||||
"priority": null,
|
||||
"spec_path": ".flow/tasks/fn-1.8.md",
|
||||
"status": "todo",
|
||||
"title": "End-to-end testing",
|
||||
"updated_at": "2026-01-12T22:41:17.996509Z"
|
||||
}
|
||||
15
.flow/tasks/fn-1.8.md
Normal file
15
.flow/tasks/fn-1.8.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# fn-1.8 End-to-end testing
|
||||
|
||||
## Description
|
||||
TBD
|
||||
|
||||
## Acceptance
|
||||
- [ ] TBD
|
||||
|
||||
## Done summary
|
||||
TBD
|
||||
|
||||
## Evidence
|
||||
- Commits:
|
||||
- Tests:
|
||||
- PRs:
|
||||
76
.flow/usage.md
Normal file
76
.flow/usage.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Flow-Next Usage Guide
|
||||
|
||||
Task tracking for AI agents. All state lives in `.flow/`.
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
.flow/bin/flowctl --help # All commands
|
||||
.flow/bin/flowctl <cmd> --help # Command help
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
.flow/
|
||||
├── bin/flowctl # CLI (this install)
|
||||
├── epics/fn-N.json # Epic metadata
|
||||
├── specs/fn-N.md # Epic specifications
|
||||
├── tasks/fn-N.M.json # Task metadata
|
||||
├── tasks/fn-N.M.md # Task specifications
|
||||
├── memory/ # Context memory
|
||||
└── meta.json # Project metadata
|
||||
```
|
||||
|
||||
## IDs
|
||||
|
||||
- Epics: `fn-N` (e.g., fn-1, fn-2)
|
||||
- Tasks: `fn-N.M` (e.g., fn-1.1, fn-1.2)
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# List
|
||||
.flow/bin/flowctl list # All epics + tasks grouped
|
||||
.flow/bin/flowctl epics # All epics with progress
|
||||
.flow/bin/flowctl tasks # All tasks
|
||||
.flow/bin/flowctl tasks --epic fn-1 # Tasks for epic
|
||||
.flow/bin/flowctl tasks --status todo # Filter by status
|
||||
|
||||
# View
|
||||
.flow/bin/flowctl show fn-1 # Epic with all tasks
|
||||
.flow/bin/flowctl show fn-1.2 # Single task
|
||||
.flow/bin/flowctl cat fn-1 # Epic spec (markdown)
|
||||
.flow/bin/flowctl cat fn-1.2 # Task spec (markdown)
|
||||
|
||||
# Status
|
||||
.flow/bin/flowctl ready --epic fn-1 # What's ready to work on
|
||||
.flow/bin/flowctl validate --all # Check structure
|
||||
|
||||
# Create
|
||||
.flow/bin/flowctl epic create --title "..."
|
||||
.flow/bin/flowctl task create --epic fn-1 --title "..."
|
||||
|
||||
# Work
|
||||
.flow/bin/flowctl start fn-1.2 # Claim task
|
||||
.flow/bin/flowctl done fn-1.2 --summary-file s.md --evidence-json e.json
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
1. `.flow/bin/flowctl epics` - list all epics
|
||||
2. `.flow/bin/flowctl ready --epic fn-N` - find available tasks
|
||||
3. `.flow/bin/flowctl start fn-N.M` - claim task
|
||||
4. Implement the task
|
||||
5. `.flow/bin/flowctl done fn-N.M --summary-file ... --evidence-json ...` - complete
|
||||
|
||||
## Evidence JSON Format
|
||||
|
||||
```json
|
||||
{"commits": ["abc123"], "tests": ["npm test"], "prs": []}
|
||||
```
|
||||
|
||||
## More Info
|
||||
|
||||
- Human docs: https://github.com/gmickel/gmickel-claude-marketplace/blob/main/plugins/flow-next/docs/flowctl.md
|
||||
- CLI reference: `.flow/bin/flowctl --help`
|
||||
2
scripts/ralph/.gitignore
vendored
Normal file
2
scripts/ralph/.gitignore
vendored
Normal file
@@ -0,0 +1,2 @@
|
||||
runs/
|
||||
*.log
|
||||
4
scripts/ralph/flowctl
Executable file
4
scripts/ralph/flowctl
Executable file
@@ -0,0 +1,4 @@
|
||||
#!/bin/bash
|
||||
# flowctl wrapper - invokes flowctl.py from the same directory
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
exec python3 "$SCRIPT_DIR/flowctl.py" "$@"
|
||||
3960
scripts/ralph/flowctl.py
Executable file
3960
scripts/ralph/flowctl.py
Executable file
File diff suppressed because it is too large
Load Diff
58
scripts/ralph/prompt_plan.md
Normal file
58
scripts/ralph/prompt_plan.md
Normal file
@@ -0,0 +1,58 @@
|
||||
You are running one Ralph plan gate iteration.
|
||||
|
||||
Inputs:
|
||||
- EPIC_ID={{EPIC_ID}}
|
||||
- PLAN_REVIEW={{PLAN_REVIEW}}
|
||||
- REQUIRE_PLAN_REVIEW={{REQUIRE_PLAN_REVIEW}}
|
||||
|
||||
Steps:
|
||||
1) Re-anchor:
|
||||
- scripts/ralph/flowctl show {{EPIC_ID}} --json
|
||||
- scripts/ralph/flowctl cat {{EPIC_ID}}
|
||||
- git status
|
||||
- git log -10 --oneline
|
||||
|
||||
Ralph mode rules (must follow):
|
||||
- If PLAN_REVIEW=rp: use `flowctl rp` wrappers (setup-review, select-add, prompt-get, chat-send).
|
||||
- If PLAN_REVIEW=codex: use `flowctl codex` wrappers (plan-review with --receipt).
|
||||
- Write receipt via bash heredoc (no Write tool) if `REVIEW_RECEIPT_PATH` set.
|
||||
- If any rule is violated, output `<promise>RETRY</promise>` and stop.
|
||||
|
||||
2) Plan review gate:
|
||||
- If PLAN_REVIEW=rp: run `/flow-next:plan-review {{EPIC_ID}} --review=rp`
|
||||
- If PLAN_REVIEW=codex: run `/flow-next:plan-review {{EPIC_ID}} --review=codex`
|
||||
- If PLAN_REVIEW=export: run `/flow-next:plan-review {{EPIC_ID}} --review=export`
|
||||
- If PLAN_REVIEW=none:
|
||||
- If REQUIRE_PLAN_REVIEW=1: output `<promise>RETRY</promise>` and stop.
|
||||
- Else: set ship and stop:
|
||||
`scripts/ralph/flowctl epic set-plan-review-status {{EPIC_ID}} --status ship --json`
|
||||
|
||||
3) The skill will loop internally until `<verdict>SHIP</verdict>`:
|
||||
- First review uses `--new-chat`
|
||||
- If NEEDS_WORK: skill fixes plan, re-reviews in SAME chat (no --new-chat)
|
||||
- Repeats until SHIP
|
||||
- Only returns to Ralph after SHIP or MAJOR_RETHINK
|
||||
|
||||
4) IMMEDIATELY after SHIP verdict, write receipt (for rp mode):
|
||||
```bash
|
||||
mkdir -p "$(dirname '{{REVIEW_RECEIPT_PATH}}')"
|
||||
ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
||||
cat > '{{REVIEW_RECEIPT_PATH}}' <<EOF
|
||||
{"type":"plan_review","id":"{{EPIC_ID}}","mode":"rp","timestamp":"$ts"}
|
||||
EOF
|
||||
```
|
||||
For codex mode, receipt is written automatically by `flowctl codex plan-review --receipt`.
|
||||
**CRITICAL: Copy EXACTLY. The `"id":"{{EPIC_ID}}"` field is REQUIRED.**
|
||||
Missing id = verification fails = forced retry.
|
||||
|
||||
5) After SHIP:
|
||||
- `scripts/ralph/flowctl epic set-plan-review-status {{EPIC_ID}} --status ship --json`
|
||||
- stop (do NOT output promise tag)
|
||||
|
||||
6) If MAJOR_RETHINK (rare):
|
||||
- `scripts/ralph/flowctl epic set-plan-review-status {{EPIC_ID}} --status needs_work --json`
|
||||
- output `<promise>FAIL</promise>` and stop
|
||||
|
||||
7) On hard failure, output `<promise>FAIL</promise>` and stop.
|
||||
|
||||
Do NOT output `<promise>COMPLETE</promise>` in this prompt.
|
||||
51
scripts/ralph/prompt_work.md
Normal file
51
scripts/ralph/prompt_work.md
Normal file
@@ -0,0 +1,51 @@
|
||||
You are running one Ralph work iteration.
|
||||
|
||||
Inputs:
|
||||
- TASK_ID={{TASK_ID}}
|
||||
- BRANCH_MODE={{BRANCH_MODE_EFFECTIVE}}
|
||||
- WORK_REVIEW={{WORK_REVIEW}}
|
||||
|
||||
## Steps (execute ALL in order)
|
||||
|
||||
**Step 1: Execute task**
|
||||
```
|
||||
/flow-next:work {{TASK_ID}} --branch={{BRANCH_MODE_EFFECTIVE}} --review={{WORK_REVIEW}}
|
||||
```
|
||||
When `--review=rp`, the work skill MUST invoke `/flow-next:impl-review` internally (see Phase 7 in skill).
|
||||
When `--review=codex`, the work skill uses `flowctl codex impl-review` for review.
|
||||
The impl-review skill handles review coordination and requires `<verdict>SHIP|NEEDS_WORK|MAJOR_RETHINK</verdict>` from reviewer.
|
||||
Do NOT improvise review prompts - the skill has the correct format.
|
||||
|
||||
**Step 2: Verify task done** (AFTER skill returns)
|
||||
```bash
|
||||
scripts/ralph/flowctl show {{TASK_ID}} --json
|
||||
```
|
||||
If status != `done`, output `<promise>RETRY</promise>` and stop.
|
||||
|
||||
**Step 3: Write impl receipt** (MANDATORY if WORK_REVIEW=rp or codex)
|
||||
For rp mode:
|
||||
```bash
|
||||
mkdir -p "$(dirname '{{REVIEW_RECEIPT_PATH}}')"
|
||||
ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
||||
cat > '{{REVIEW_RECEIPT_PATH}}' <<EOF
|
||||
{"type":"impl_review","id":"{{TASK_ID}}","mode":"rp","timestamp":"$ts"}
|
||||
EOF
|
||||
echo "Receipt written: {{REVIEW_RECEIPT_PATH}}"
|
||||
```
|
||||
For codex mode, receipt is written automatically by `flowctl codex impl-review --receipt`.
|
||||
**CRITICAL: Copy the command EXACTLY. The `"id":"{{TASK_ID}}"` field is REQUIRED.**
|
||||
Ralph verifies receipts match this exact schema. Missing id = verification fails = forced retry.
|
||||
|
||||
**Step 4: Validate epic**
|
||||
```bash
|
||||
scripts/ralph/flowctl validate --epic $(echo {{TASK_ID}} | sed 's/\.[0-9]*$//') --json
|
||||
```
|
||||
|
||||
**Step 5: On hard failure** → output `<promise>FAIL</promise>` and stop.
|
||||
|
||||
## Rules
|
||||
- Must run `flowctl done` and verify task status is `done` before commit.
|
||||
- Must `git add -A` (never list files).
|
||||
- Do NOT use TodoWrite.
|
||||
|
||||
Do NOT output `<promise>COMPLETE</promise>` in this prompt.
|
||||
907
scripts/ralph/ralph.sh
Executable file
907
scripts/ralph/ralph.sh
Executable file
@@ -0,0 +1,907 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
|
||||
CONFIG="$SCRIPT_DIR/config.env"
|
||||
FLOWCTL="$SCRIPT_DIR/flowctl"
|
||||
|
||||
fail() { echo "ralph: $*" >&2; exit 1; }
|
||||
log() {
|
||||
# Machine-readable logs: only show when UI disabled
|
||||
[[ "${UI_ENABLED:-1}" != "1" ]] && echo "ralph: $*"
|
||||
return 0
|
||||
}
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# Presentation layer (human-readable output)
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
UI_ENABLED="${RALPH_UI:-1}" # set RALPH_UI=0 to disable
|
||||
|
||||
# Timing
|
||||
START_TIME="$(date +%s)"
|
||||
|
||||
elapsed_time() {
|
||||
local now elapsed mins secs
|
||||
now="$(date +%s)"
|
||||
elapsed=$((now - START_TIME))
|
||||
mins=$((elapsed / 60))
|
||||
secs=$((elapsed % 60))
|
||||
printf "%d:%02d" "$mins" "$secs"
|
||||
}
|
||||
|
||||
# Stats tracking
|
||||
STATS_TASKS_DONE=0
|
||||
|
||||
# Colors (disabled if not tty or NO_COLOR set)
|
||||
if [[ -t 1 && -z "${NO_COLOR:-}" ]]; then
|
||||
C_RESET='\033[0m'
|
||||
C_BOLD='\033[1m'
|
||||
C_DIM='\033[2m'
|
||||
C_BLUE='\033[34m'
|
||||
C_GREEN='\033[32m'
|
||||
C_YELLOW='\033[33m'
|
||||
C_RED='\033[31m'
|
||||
C_CYAN='\033[36m'
|
||||
C_MAGENTA='\033[35m'
|
||||
else
|
||||
C_RESET='' C_BOLD='' C_DIM='' C_BLUE='' C_GREEN='' C_YELLOW='' C_RED='' C_CYAN='' C_MAGENTA=''
|
||||
fi
|
||||
|
||||
# Watch mode: "", "tools", "verbose"
|
||||
WATCH_MODE=""
|
||||
|
||||
ui() {
|
||||
[[ "$UI_ENABLED" == "1" ]] || return 0
|
||||
echo -e "$*"
|
||||
}
|
||||
|
||||
# Get title from epic/task JSON
|
||||
get_title() {
|
||||
local json="$1"
|
||||
python3 - "$json" <<'PY'
|
||||
import json, sys
|
||||
try:
|
||||
data = json.loads(sys.argv[1])
|
||||
print(data.get("title", "")[:40])
|
||||
except:
|
||||
print("")
|
||||
PY
|
||||
}
|
||||
|
||||
# Count progress (done/total tasks for scoped epics)
|
||||
get_progress() {
|
||||
python3 - "$ROOT_DIR" "${EPICS_FILE:-}" <<'PY'
|
||||
import json, sys
|
||||
from pathlib import Path
|
||||
root = Path(sys.argv[1])
|
||||
epics_file = sys.argv[2] if len(sys.argv) > 2 else ""
|
||||
flow_dir = root / ".flow"
|
||||
|
||||
# Get scoped epics or all
|
||||
scoped = []
|
||||
if epics_file:
|
||||
try:
|
||||
scoped = json.load(open(epics_file))["epics"]
|
||||
except:
|
||||
pass
|
||||
|
||||
epics_dir = flow_dir / "epics"
|
||||
tasks_dir = flow_dir / "tasks"
|
||||
if not epics_dir.exists():
|
||||
print("0|0|0|0")
|
||||
sys.exit(0)
|
||||
|
||||
epic_ids = []
|
||||
for f in sorted(epics_dir.glob("fn-*.json")):
|
||||
eid = f.stem
|
||||
if not scoped or eid in scoped:
|
||||
epic_ids.append(eid)
|
||||
|
||||
epics_done = sum(1 for e in epic_ids if json.load(open(epics_dir / f"{e}.json")).get("status") == "done")
|
||||
tasks_total = 0
|
||||
tasks_done = 0
|
||||
if tasks_dir.exists():
|
||||
for tf in tasks_dir.glob("*.json"):
|
||||
try:
|
||||
t = json.load(open(tf))
|
||||
epic_id = tf.stem.rsplit(".", 1)[0]
|
||||
if not scoped or epic_id in scoped:
|
||||
tasks_total += 1
|
||||
if t.get("status") == "done":
|
||||
tasks_done += 1
|
||||
except:
|
||||
pass
|
||||
print(f"{epics_done}|{len(epic_ids)}|{tasks_done}|{tasks_total}")
|
||||
PY
|
||||
}
|
||||
|
||||
# Get git diff stats
|
||||
get_git_stats() {
|
||||
local base_branch="${1:-main}"
|
||||
local stats
|
||||
stats="$(git -C "$ROOT_DIR" diff --shortstat "$base_branch"...HEAD 2>/dev/null || true)"
|
||||
if [[ -z "$stats" ]]; then
|
||||
echo ""
|
||||
return
|
||||
fi
|
||||
python3 - "$stats" <<'PY'
|
||||
import re, sys
|
||||
s = sys.argv[1]
|
||||
files = re.search(r"(\d+) files? changed", s)
|
||||
ins = re.search(r"(\d+) insertions?", s)
|
||||
dels = re.search(r"(\d+) deletions?", s)
|
||||
f = files.group(1) if files else "0"
|
||||
i = ins.group(1) if ins else "0"
|
||||
d = dels.group(1) if dels else "0"
|
||||
print(f"{f} files, +{i} -{d}")
|
||||
PY
|
||||
}
|
||||
|
||||
ui_header() {
|
||||
ui ""
|
||||
ui "${C_BOLD}${C_BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
|
||||
ui "${C_BOLD}${C_BLUE} 🤖 Ralph Autonomous Loop${C_RESET}"
|
||||
ui "${C_BOLD}${C_BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
|
||||
}
|
||||
|
||||
ui_config() {
|
||||
local git_branch progress_info epics_done epics_total tasks_done tasks_total
|
||||
git_branch="$(git -C "$ROOT_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")"
|
||||
progress_info="$(get_progress)"
|
||||
IFS='|' read -r epics_done epics_total tasks_done tasks_total <<< "$progress_info"
|
||||
|
||||
ui ""
|
||||
ui "${C_DIM} Branch:${C_RESET} ${C_BOLD}$git_branch${C_RESET}"
|
||||
ui "${C_DIM} Progress:${C_RESET} Epic ${epics_done}/${epics_total} ${C_DIM}•${C_RESET} Task ${tasks_done}/${tasks_total}"
|
||||
|
||||
local plan_display="$PLAN_REVIEW" work_display="$WORK_REVIEW"
|
||||
[[ "$PLAN_REVIEW" == "rp" ]] && plan_display="RepoPrompt"
|
||||
[[ "$PLAN_REVIEW" == "codex" ]] && plan_display="Codex"
|
||||
[[ "$WORK_REVIEW" == "rp" ]] && work_display="RepoPrompt"
|
||||
[[ "$WORK_REVIEW" == "codex" ]] && work_display="Codex"
|
||||
ui "${C_DIM} Reviews:${C_RESET} Plan=$plan_display ${C_DIM}•${C_RESET} Work=$work_display"
|
||||
[[ -n "${EPICS:-}" ]] && ui "${C_DIM} Scope:${C_RESET} $EPICS"
|
||||
ui ""
|
||||
}
|
||||
|
||||
ui_iteration() {
|
||||
local iter="$1" status="$2" epic="${3:-}" task="${4:-}" title="" item_json=""
|
||||
local elapsed
|
||||
elapsed="$(elapsed_time)"
|
||||
ui ""
|
||||
ui "${C_BOLD}${C_CYAN}🔄 Iteration $iter${C_RESET} ${C_DIM}[${elapsed}]${C_RESET}"
|
||||
if [[ "$status" == "plan" ]]; then
|
||||
item_json="$("$FLOWCTL" show "$epic" --json 2>/dev/null || true)"
|
||||
title="$(get_title "$item_json")"
|
||||
ui " ${C_DIM}Epic:${C_RESET} ${C_BOLD}$epic${C_RESET} ${C_DIM}\"$title\"${C_RESET}"
|
||||
ui " ${C_DIM}Phase:${C_RESET} ${C_YELLOW}Planning${C_RESET}"
|
||||
elif [[ "$status" == "work" ]]; then
|
||||
item_json="$("$FLOWCTL" show "$task" --json 2>/dev/null || true)"
|
||||
title="$(get_title "$item_json")"
|
||||
ui " ${C_DIM}Task:${C_RESET} ${C_BOLD}$task${C_RESET} ${C_DIM}\"$title\"${C_RESET}"
|
||||
ui " ${C_DIM}Phase:${C_RESET} ${C_MAGENTA}Implementation${C_RESET}"
|
||||
fi
|
||||
}
|
||||
|
||||
ui_plan_review() {
|
||||
local mode="$1" epic="$2"
|
||||
if [[ "$mode" == "rp" ]]; then
|
||||
ui ""
|
||||
ui " ${C_YELLOW}📝 Plan Review${C_RESET}"
|
||||
ui " ${C_DIM}Sending to reviewer via RepoPrompt...${C_RESET}"
|
||||
elif [[ "$mode" == "codex" ]]; then
|
||||
ui ""
|
||||
ui " ${C_YELLOW}📝 Plan Review${C_RESET}"
|
||||
ui " ${C_DIM}Sending to reviewer via Codex...${C_RESET}"
|
||||
fi
|
||||
}
|
||||
|
||||
ui_impl_review() {
|
||||
local mode="$1" task="$2"
|
||||
if [[ "$mode" == "rp" ]]; then
|
||||
ui ""
|
||||
ui " ${C_MAGENTA}🔍 Implementation Review${C_RESET}"
|
||||
ui " ${C_DIM}Sending to reviewer via RepoPrompt...${C_RESET}"
|
||||
elif [[ "$mode" == "codex" ]]; then
|
||||
ui ""
|
||||
ui " ${C_MAGENTA}🔍 Implementation Review${C_RESET}"
|
||||
ui " ${C_DIM}Sending to reviewer via Codex...${C_RESET}"
|
||||
fi
|
||||
}
|
||||
|
||||
ui_task_done() {
|
||||
local task="$1" git_stats=""
|
||||
STATS_TASKS_DONE=$((STATS_TASKS_DONE + 1))
|
||||
init_branches_file 2>/dev/null || true
|
||||
local base_branch
|
||||
base_branch="$(get_base_branch 2>/dev/null || echo "main")"
|
||||
git_stats="$(get_git_stats "$base_branch")"
|
||||
if [[ -n "$git_stats" ]]; then
|
||||
ui " ${C_GREEN}✓${C_RESET} ${C_BOLD}$task${C_RESET} ${C_DIM}($git_stats)${C_RESET}"
|
||||
else
|
||||
ui " ${C_GREEN}✓${C_RESET} ${C_BOLD}$task${C_RESET}"
|
||||
fi
|
||||
}
|
||||
|
||||
ui_retry() {
|
||||
local task="$1" attempts="$2" max="$3"
|
||||
ui " ${C_YELLOW}↻ Retry${C_RESET} ${C_DIM}(attempt $attempts/$max)${C_RESET}"
|
||||
}
|
||||
|
||||
ui_blocked() {
|
||||
local task="$1"
|
||||
ui " ${C_RED}🚫 Task blocked:${C_RESET} $task ${C_DIM}(max attempts reached)${C_RESET}"
|
||||
}
|
||||
|
||||
ui_complete() {
|
||||
local elapsed progress_info epics_done epics_total tasks_done tasks_total
|
||||
elapsed="$(elapsed_time)"
|
||||
progress_info="$(get_progress)"
|
||||
IFS='|' read -r epics_done epics_total tasks_done tasks_total <<< "$progress_info"
|
||||
|
||||
ui ""
|
||||
ui "${C_BOLD}${C_GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
|
||||
ui "${C_BOLD}${C_GREEN} ✅ Ralph Complete${C_RESET} ${C_DIM}[${elapsed}]${C_RESET}"
|
||||
ui ""
|
||||
ui " ${C_DIM}Tasks:${C_RESET} ${tasks_done}/${tasks_total} ${C_DIM}•${C_RESET} ${C_DIM}Epics:${C_RESET} ${epics_done}/${epics_total}"
|
||||
ui "${C_BOLD}${C_GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
|
||||
ui ""
|
||||
}
|
||||
|
||||
ui_fail() {
|
||||
local reason="${1:-}" elapsed
|
||||
elapsed="$(elapsed_time)"
|
||||
ui ""
|
||||
ui "${C_BOLD}${C_RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
|
||||
ui "${C_BOLD}${C_RED} ❌ Ralph Failed${C_RESET} ${C_DIM}[${elapsed}]${C_RESET}"
|
||||
[[ -n "$reason" ]] && ui " ${C_DIM}$reason${C_RESET}"
|
||||
ui "${C_BOLD}${C_RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RESET}"
|
||||
ui ""
|
||||
}
|
||||
|
||||
ui_waiting() {
|
||||
ui " ${C_DIM}⏳ Claude working...${C_RESET}"
|
||||
}
|
||||
|
||||
[[ -f "$CONFIG" ]] || fail "missing config.env"
|
||||
[[ -x "$FLOWCTL" ]] || fail "missing flowctl"
|
||||
|
||||
# shellcheck disable=SC1090
|
||||
set -a
|
||||
source "$CONFIG"
|
||||
set +a
|
||||
|
||||
MAX_ITERATIONS="${MAX_ITERATIONS:-25}"
|
||||
MAX_TURNS="${MAX_TURNS:-}" # empty = no limit; Claude stops via promise tags
|
||||
MAX_ATTEMPTS_PER_TASK="${MAX_ATTEMPTS_PER_TASK:-5}"
|
||||
WORKER_TIMEOUT="${WORKER_TIMEOUT:-1800}" # 30min default; prevents stuck workers
|
||||
BRANCH_MODE="${BRANCH_MODE:-new}"
|
||||
PLAN_REVIEW="${PLAN_REVIEW:-none}"
|
||||
WORK_REVIEW="${WORK_REVIEW:-none}"
|
||||
REQUIRE_PLAN_REVIEW="${REQUIRE_PLAN_REVIEW:-0}"
|
||||
YOLO="${YOLO:-0}"
|
||||
EPICS="${EPICS:-}"
|
||||
|
||||
# Parse command line arguments
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--watch)
|
||||
if [[ "${2:-}" == "verbose" ]]; then
|
||||
WATCH_MODE="verbose"
|
||||
shift
|
||||
else
|
||||
WATCH_MODE="tools"
|
||||
fi
|
||||
shift
|
||||
;;
|
||||
--help|-h)
|
||||
echo "Usage: ralph.sh [options]"
|
||||
echo ""
|
||||
echo "Options:"
|
||||
echo " --watch Show tool calls in real-time"
|
||||
echo " --watch verbose Show tool calls + model responses"
|
||||
echo " --help, -h Show this help"
|
||||
echo ""
|
||||
echo "Environment variables:"
|
||||
echo " EPICS Comma/space-separated epic IDs to work on"
|
||||
echo " MAX_ITERATIONS Max loop iterations (default: 25)"
|
||||
echo " YOLO Set to 1 to skip permissions (required for unattended)"
|
||||
echo ""
|
||||
echo "See config.env for more options."
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
fail "Unknown option: $1 (use --help for usage)"
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Set up signal trap for watch mode (pipe chains need clean Ctrl+C handling)
|
||||
if [[ -n "$WATCH_MODE" ]]; then
|
||||
cleanup() { kill -- -$$ 2>/dev/null; exit 130; }
|
||||
trap cleanup SIGINT SIGTERM
|
||||
fi
|
||||
|
||||
CLAUDE_BIN="${CLAUDE_BIN:-claude}"
|
||||
|
||||
# Detect timeout command (GNU coreutils). On macOS: brew install coreutils
|
||||
if command -v timeout >/dev/null 2>&1; then
|
||||
TIMEOUT_CMD="timeout"
|
||||
elif command -v gtimeout >/dev/null 2>&1; then
|
||||
TIMEOUT_CMD="gtimeout"
|
||||
else
|
||||
TIMEOUT_CMD=""
|
||||
echo "ralph: warning: timeout command not found; worker timeout disabled (brew install coreutils)" >&2
|
||||
fi
|
||||
|
||||
sanitize_id() {
|
||||
local v="$1"
|
||||
v="${v// /_}"
|
||||
v="${v//\//_}"
|
||||
v="${v//\\/__}"
|
||||
echo "$v"
|
||||
}
|
||||
|
||||
get_actor() {
|
||||
if [[ -n "${FLOW_ACTOR:-}" ]]; then echo "$FLOW_ACTOR"; return; fi
|
||||
if actor="$(git -C "$ROOT_DIR" config user.email 2>/dev/null)"; then
|
||||
[[ -n "$actor" ]] && { echo "$actor"; return; }
|
||||
fi
|
||||
if actor="$(git -C "$ROOT_DIR" config user.name 2>/dev/null)"; then
|
||||
[[ -n "$actor" ]] && { echo "$actor"; return; }
|
||||
fi
|
||||
echo "${USER:-unknown}"
|
||||
}
|
||||
|
||||
rand4() {
|
||||
python3 - <<'PY'
|
||||
import secrets
|
||||
print(secrets.token_hex(2))
|
||||
PY
|
||||
}
|
||||
|
||||
render_template() {
|
||||
local path="$1"
|
||||
python3 - "$path" <<'PY'
|
||||
import os, sys
|
||||
path = sys.argv[1]
|
||||
text = open(path, encoding="utf-8").read()
|
||||
keys = ["EPIC_ID","TASK_ID","PLAN_REVIEW","WORK_REVIEW","BRANCH_MODE","BRANCH_MODE_EFFECTIVE","REQUIRE_PLAN_REVIEW","REVIEW_RECEIPT_PATH"]
|
||||
for k in keys:
|
||||
text = text.replace("{{%s}}" % k, os.environ.get(k, ""))
|
||||
print(text)
|
||||
PY
|
||||
}
|
||||
|
||||
json_get() {
|
||||
local key="$1"
|
||||
local json="$2"
|
||||
python3 - "$key" "$json" <<'PY'
|
||||
import json, sys
|
||||
key = sys.argv[1]
|
||||
data = json.loads(sys.argv[2])
|
||||
val = data.get(key)
|
||||
if val is None:
|
||||
print("")
|
||||
elif isinstance(val, bool):
|
||||
print("1" if val else "0")
|
||||
else:
|
||||
print(val)
|
||||
PY
|
||||
}
|
||||
|
||||
ensure_attempts_file() {
|
||||
[[ -f "$1" ]] || echo "{}" > "$1"
|
||||
}
|
||||
|
||||
bump_attempts() {
|
||||
python3 - "$1" "$2" <<'PY'
|
||||
import json, sys, os
|
||||
path, task = sys.argv[1], sys.argv[2]
|
||||
data = {}
|
||||
if os.path.exists(path):
|
||||
with open(path, encoding="utf-8") as f:
|
||||
data = json.load(f)
|
||||
count = int(data.get(task, 0)) + 1
|
||||
data[task] = count
|
||||
with open(path, "w", encoding="utf-8") as f:
|
||||
json.dump(data, f, indent=2, sort_keys=True)
|
||||
print(count)
|
||||
PY
|
||||
}
|
||||
|
||||
write_epics_file() {
|
||||
python3 - "$1" <<'PY'
|
||||
import json, sys
|
||||
raw = sys.argv[1]
|
||||
parts = [p.strip() for p in raw.replace(",", " ").split() if p.strip()]
|
||||
print(json.dumps({"epics": parts}, indent=2, sort_keys=True))
|
||||
PY
|
||||
}
|
||||
|
||||
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$(hostname -s 2>/dev/null || hostname)-$(sanitize_id "$(get_actor)")-$$-$(rand4)"
|
||||
RUN_DIR="$SCRIPT_DIR/runs/$RUN_ID"
|
||||
mkdir -p "$RUN_DIR"
|
||||
ATTEMPTS_FILE="$RUN_DIR/attempts.json"
|
||||
ensure_attempts_file "$ATTEMPTS_FILE"
|
||||
BRANCHES_FILE="$RUN_DIR/branches.json"
|
||||
RECEIPTS_DIR="$RUN_DIR/receipts"
|
||||
mkdir -p "$RECEIPTS_DIR"
|
||||
PROGRESS_FILE="$RUN_DIR/progress.txt"
|
||||
{
|
||||
echo "# Ralph Progress Log"
|
||||
echo "Run: $RUN_ID"
|
||||
echo "Started: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
||||
echo "---"
|
||||
} > "$PROGRESS_FILE"
|
||||
|
||||
extract_tag() {
|
||||
local tag="$1"
|
||||
python3 - "$tag" <<'PY'
|
||||
import re, sys
|
||||
tag = sys.argv[1]
|
||||
text = sys.stdin.read()
|
||||
matches = re.findall(rf"<{tag}>(.*?)</{tag}>", text, flags=re.S)
|
||||
print(matches[-1] if matches else "")
|
||||
PY
|
||||
}
|
||||
|
||||
# Extract assistant text from stream-json log (for tag extraction in watch mode)
|
||||
extract_text_from_stream_json() {
|
||||
local log_file="$1"
|
||||
python3 - "$log_file" <<'PY'
|
||||
import json, sys
|
||||
path = sys.argv[1]
|
||||
out = []
|
||||
try:
|
||||
with open(path, encoding="utf-8") as f:
|
||||
for line in f:
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
try:
|
||||
ev = json.loads(line)
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
if ev.get("type") != "assistant":
|
||||
continue
|
||||
msg = ev.get("message") or {}
|
||||
for blk in (msg.get("content") or []):
|
||||
if blk.get("type") == "text":
|
||||
out.append(blk.get("text", ""))
|
||||
except Exception:
|
||||
pass
|
||||
print("\n".join(out))
|
||||
PY
|
||||
}
|
||||
|
||||
append_progress() {
|
||||
local verdict="$1"
|
||||
local promise="$2"
|
||||
local plan_review_status="${3:-}"
|
||||
local task_status="${4:-}"
|
||||
local receipt_exists="0"
|
||||
if [[ -n "${REVIEW_RECEIPT_PATH:-}" && -f "$REVIEW_RECEIPT_PATH" ]]; then
|
||||
receipt_exists="1"
|
||||
fi
|
||||
{
|
||||
echo "## $(date -u +%Y-%m-%dT%H:%M:%SZ) - iter $iter"
|
||||
echo "status=$status epic=${epic_id:-} task=${task_id:-} reason=${reason:-}"
|
||||
echo "claude_rc=$claude_rc"
|
||||
echo "verdict=${verdict:-}"
|
||||
echo "promise=${promise:-}"
|
||||
echo "receipt=${REVIEW_RECEIPT_PATH:-} exists=$receipt_exists"
|
||||
echo "plan_review_status=${plan_review_status:-}"
|
||||
echo "task_status=${task_status:-}"
|
||||
echo "iter_log=$iter_log"
|
||||
echo "last_output:"
|
||||
tail -n 10 "$iter_log" || true
|
||||
echo "---"
|
||||
} >> "$PROGRESS_FILE"
|
||||
}
|
||||
|
||||
init_branches_file() {
|
||||
if [[ -f "$BRANCHES_FILE" ]]; then return; fi
|
||||
local base_branch
|
||||
base_branch="$(git -C "$ROOT_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
|
||||
python3 - "$BRANCHES_FILE" "$base_branch" <<'PY'
|
||||
import json, sys
|
||||
path, base = sys.argv[1], sys.argv[2]
|
||||
data = {"base_branch": base, "run_branch": ""}
|
||||
with open(path, "w", encoding="utf-8") as f:
|
||||
json.dump(data, f, indent=2, sort_keys=True)
|
||||
PY
|
||||
}
|
||||
|
||||
get_base_branch() {
|
||||
python3 - "$BRANCHES_FILE" <<'PY'
|
||||
import json, sys
|
||||
try:
|
||||
with open(sys.argv[1], encoding="utf-8") as f:
|
||||
data = json.load(f)
|
||||
print(data.get("base_branch", ""))
|
||||
except FileNotFoundError:
|
||||
print("")
|
||||
PY
|
||||
}
|
||||
|
||||
get_run_branch() {
|
||||
python3 - "$BRANCHES_FILE" <<'PY'
|
||||
import json, sys
|
||||
try:
|
||||
with open(sys.argv[1], encoding="utf-8") as f:
|
||||
data = json.load(f)
|
||||
print(data.get("run_branch", ""))
|
||||
except FileNotFoundError:
|
||||
print("")
|
||||
PY
|
||||
}
|
||||
|
||||
set_run_branch() {
|
||||
python3 - "$BRANCHES_FILE" "$1" <<'PY'
|
||||
import json, sys
|
||||
path, branch = sys.argv[1], sys.argv[2]
|
||||
data = {"base_branch": "", "run_branch": ""}
|
||||
try:
|
||||
with open(path, encoding="utf-8") as f:
|
||||
data = json.load(f)
|
||||
except FileNotFoundError:
|
||||
pass
|
||||
data["run_branch"] = branch
|
||||
with open(path, "w", encoding="utf-8") as f:
|
||||
json.dump(data, f, indent=2, sort_keys=True)
|
||||
PY
|
||||
}
|
||||
|
||||
list_epics_from_file() {
|
||||
python3 - "$EPICS_FILE" <<'PY'
|
||||
import json, sys
|
||||
path = sys.argv[1]
|
||||
if not path:
|
||||
sys.exit(0)
|
||||
try:
|
||||
data = json.load(open(path, encoding="utf-8"))
|
||||
except FileNotFoundError:
|
||||
sys.exit(0)
|
||||
epics = data.get("epics", []) or []
|
||||
print(" ".join(epics))
|
||||
PY
|
||||
}
|
||||
|
||||
epic_all_tasks_done() {
|
||||
python3 - "$1" <<'PY'
|
||||
import json, sys
|
||||
try:
|
||||
data = json.loads(sys.argv[1])
|
||||
except json.JSONDecodeError:
|
||||
print("0")
|
||||
sys.exit(0)
|
||||
tasks = data.get("tasks", []) or []
|
||||
if not tasks:
|
||||
print("0")
|
||||
sys.exit(0)
|
||||
for t in tasks:
|
||||
if t.get("status") != "done":
|
||||
print("0")
|
||||
sys.exit(0)
|
||||
print("1")
|
||||
PY
|
||||
}
|
||||
|
||||
maybe_close_epics() {
|
||||
[[ -z "$EPICS_FILE" ]] && return 0
|
||||
local epics json status all_done
|
||||
epics="$(list_epics_from_file)"
|
||||
[[ -z "$epics" ]] && return 0
|
||||
for epic in $epics; do
|
||||
json="$("$FLOWCTL" show "$epic" --json 2>/dev/null || true)"
|
||||
[[ -z "$json" ]] && continue
|
||||
status="$(json_get status "$json")"
|
||||
[[ "$status" == "done" ]] && continue
|
||||
all_done="$(epic_all_tasks_done "$json")"
|
||||
if [[ "$all_done" == "1" ]]; then
|
||||
"$FLOWCTL" epic close "$epic" --json >/dev/null 2>&1 || true
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
verify_receipt() {
|
||||
local path="$1"
|
||||
local kind="$2"
|
||||
local id="$3"
|
||||
[[ -f "$path" ]] || return 1
|
||||
python3 - "$path" "$kind" "$id" <<'PY'
|
||||
import json, sys
|
||||
path, kind, rid = sys.argv[1], sys.argv[2], sys.argv[3]
|
||||
try:
|
||||
data = json.load(open(path, encoding="utf-8"))
|
||||
except Exception:
|
||||
sys.exit(1)
|
||||
if data.get("type") != kind:
|
||||
sys.exit(1)
|
||||
if data.get("id") != rid:
|
||||
sys.exit(1)
|
||||
sys.exit(0)
|
||||
PY
|
||||
}
|
||||
|
||||
# Create/switch to run branch (once at start, all epics work here)
|
||||
ensure_run_branch() {
|
||||
if [[ "$BRANCH_MODE" != "new" ]]; then
|
||||
return
|
||||
fi
|
||||
init_branches_file
|
||||
local branch
|
||||
branch="$(get_run_branch)"
|
||||
if [[ -n "$branch" ]]; then
|
||||
# Already on run branch (resumed run)
|
||||
git -C "$ROOT_DIR" checkout "$branch" >/dev/null 2>&1 || true
|
||||
return
|
||||
fi
|
||||
# Create new run branch from current position
|
||||
branch="ralph-${RUN_ID}"
|
||||
set_run_branch "$branch"
|
||||
git -C "$ROOT_DIR" checkout -b "$branch" >/dev/null 2>&1
|
||||
}
|
||||
|
||||
EPICS_FILE=""
|
||||
if [[ -n "${EPICS// }" ]]; then
|
||||
EPICS_FILE="$RUN_DIR/run.json"
|
||||
write_epics_file "$EPICS" > "$EPICS_FILE"
|
||||
fi
|
||||
|
||||
ui_header
|
||||
ui_config
|
||||
|
||||
# Create run branch once at start (all epics work on same branch)
|
||||
ensure_run_branch
|
||||
|
||||
iter=1
|
||||
while (( iter <= MAX_ITERATIONS )); do
|
||||
iter_log="$RUN_DIR/iter-$(printf '%03d' "$iter").log"
|
||||
|
||||
selector_args=("$FLOWCTL" next --json)
|
||||
[[ -n "$EPICS_FILE" ]] && selector_args+=(--epics-file "$EPICS_FILE")
|
||||
[[ "$REQUIRE_PLAN_REVIEW" == "1" ]] && selector_args+=(--require-plan-review)
|
||||
|
||||
selector_json="$("${selector_args[@]}")"
|
||||
status="$(json_get status "$selector_json")"
|
||||
epic_id="$(json_get epic "$selector_json")"
|
||||
task_id="$(json_get task "$selector_json")"
|
||||
reason="$(json_get reason "$selector_json")"
|
||||
|
||||
log "iter $iter status=$status epic=${epic_id:-} task=${task_id:-} reason=${reason:-}"
|
||||
ui_iteration "$iter" "$status" "${epic_id:-}" "${task_id:-}"
|
||||
|
||||
if [[ "$status" == "none" ]]; then
|
||||
if [[ "$reason" == "blocked_by_epic_deps" ]]; then
|
||||
log "blocked by epic deps"
|
||||
fi
|
||||
maybe_close_epics
|
||||
ui_complete
|
||||
echo "<promise>COMPLETE</promise>"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [[ "$status" == "plan" ]]; then
|
||||
export EPIC_ID="$epic_id"
|
||||
export PLAN_REVIEW
|
||||
export REQUIRE_PLAN_REVIEW
|
||||
if [[ "$PLAN_REVIEW" != "none" ]]; then
|
||||
export REVIEW_RECEIPT_PATH="$RECEIPTS_DIR/plan-${epic_id}.json"
|
||||
else
|
||||
unset REVIEW_RECEIPT_PATH
|
||||
fi
|
||||
log "plan epic=$epic_id review=$PLAN_REVIEW receipt=${REVIEW_RECEIPT_PATH:-} require=$REQUIRE_PLAN_REVIEW"
|
||||
ui_plan_review "$PLAN_REVIEW" "$epic_id"
|
||||
prompt="$(render_template "$SCRIPT_DIR/prompt_plan.md")"
|
||||
elif [[ "$status" == "work" ]]; then
|
||||
epic_id="${task_id%%.*}"
|
||||
export TASK_ID="$task_id"
|
||||
BRANCH_MODE_EFFECTIVE="$BRANCH_MODE"
|
||||
if [[ "$BRANCH_MODE" == "new" ]]; then
|
||||
BRANCH_MODE_EFFECTIVE="current"
|
||||
fi
|
||||
export BRANCH_MODE_EFFECTIVE
|
||||
export WORK_REVIEW
|
||||
if [[ "$WORK_REVIEW" != "none" ]]; then
|
||||
export REVIEW_RECEIPT_PATH="$RECEIPTS_DIR/impl-${task_id}.json"
|
||||
else
|
||||
unset REVIEW_RECEIPT_PATH
|
||||
fi
|
||||
log "work task=$task_id review=$WORK_REVIEW receipt=${REVIEW_RECEIPT_PATH:-} branch=$BRANCH_MODE_EFFECTIVE"
|
||||
ui_impl_review "$WORK_REVIEW" "$task_id"
|
||||
prompt="$(render_template "$SCRIPT_DIR/prompt_work.md")"
|
||||
else
|
||||
fail "invalid selector status: $status"
|
||||
fi
|
||||
|
||||
export FLOW_RALPH="1"
|
||||
claude_args=(-p)
|
||||
# Set output format based on watch mode (stream-json required for real-time output)
|
||||
if [[ -n "$WATCH_MODE" ]]; then
|
||||
claude_args+=(--output-format stream-json)
|
||||
else
|
||||
claude_args+=(--output-format text)
|
||||
fi
|
||||
|
||||
# Autonomous mode system prompt - critical for preventing drift
|
||||
claude_args+=(--append-system-prompt "AUTONOMOUS MODE ACTIVE (FLOW_RALPH=1). You are running unattended. CRITICAL RULES:
|
||||
1. EXECUTE COMMANDS EXACTLY as shown in prompts. Do not paraphrase or improvise.
|
||||
2. VERIFY OUTCOMES by running the verification commands (flowctl show, git status).
|
||||
3. NEVER CLAIM SUCCESS without proof. If flowctl done was not run, the task is NOT done.
|
||||
4. COPY TEMPLATES VERBATIM - receipt JSON must match exactly including all fields.
|
||||
5. USE SKILLS AS SPECIFIED - invoke /flow-next:impl-review, do not improvise review prompts.
|
||||
Violations break automation and leave the user with incomplete work. Be precise, not creative.")
|
||||
|
||||
[[ -n "${MAX_TURNS:-}" ]] && claude_args+=(--max-turns "$MAX_TURNS")
|
||||
[[ "$YOLO" == "1" ]] && claude_args+=(--dangerously-skip-permissions)
|
||||
[[ -n "${FLOW_RALPH_CLAUDE_PLUGIN_DIR:-}" ]] && claude_args+=(--plugin-dir "$FLOW_RALPH_CLAUDE_PLUGIN_DIR")
|
||||
[[ -n "${FLOW_RALPH_CLAUDE_MODEL:-}" ]] && claude_args+=(--model "$FLOW_RALPH_CLAUDE_MODEL")
|
||||
[[ -n "${FLOW_RALPH_CLAUDE_SESSION_ID:-}" ]] && claude_args+=(--session-id "$FLOW_RALPH_CLAUDE_SESSION_ID")
|
||||
[[ -n "${FLOW_RALPH_CLAUDE_PERMISSION_MODE:-}" ]] && claude_args+=(--permission-mode "$FLOW_RALPH_CLAUDE_PERMISSION_MODE")
|
||||
[[ "${FLOW_RALPH_CLAUDE_NO_SESSION_PERSISTENCE:-}" == "1" ]] && claude_args+=(--no-session-persistence)
|
||||
if [[ -n "${FLOW_RALPH_CLAUDE_DEBUG:-}" ]]; then
|
||||
if [[ "${FLOW_RALPH_CLAUDE_DEBUG}" == "1" ]]; then
|
||||
claude_args+=(--debug)
|
||||
else
|
||||
claude_args+=(--debug "$FLOW_RALPH_CLAUDE_DEBUG")
|
||||
fi
|
||||
fi
|
||||
[[ "${FLOW_RALPH_CLAUDE_VERBOSE:-}" == "1" ]] && claude_args+=(--verbose)
|
||||
|
||||
ui_waiting
|
||||
claude_out=""
|
||||
set +e
|
||||
[[ -n "${FLOW_RALPH_CLAUDE_PLUGIN_DIR:-}" ]] && claude_args+=(--plugin-dir "$FLOW_RALPH_CLAUDE_PLUGIN_DIR")
|
||||
if [[ "$WATCH_MODE" == "verbose" ]]; then
|
||||
# Full output: stream through filter with --verbose to show text/thinking
|
||||
[[ ! " ${claude_args[*]} " =~ " --verbose " ]] && claude_args+=(--verbose)
|
||||
echo ""
|
||||
if [[ -n "$TIMEOUT_CMD" ]]; then
|
||||
"$TIMEOUT_CMD" "$WORKER_TIMEOUT" "$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1 | tee "$iter_log" | "$SCRIPT_DIR/watch-filter.py" --verbose
|
||||
else
|
||||
"$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1 | tee "$iter_log" | "$SCRIPT_DIR/watch-filter.py" --verbose
|
||||
fi
|
||||
claude_rc=${PIPESTATUS[0]}
|
||||
claude_out="$(cat "$iter_log")"
|
||||
elif [[ "$WATCH_MODE" == "tools" ]]; then
|
||||
# Filtered output: stream-json through watch-filter.py
|
||||
# Add --verbose only if not already set (needed for tool visibility)
|
||||
[[ ! " ${claude_args[*]} " =~ " --verbose " ]] && claude_args+=(--verbose)
|
||||
if [[ -n "$TIMEOUT_CMD" ]]; then
|
||||
"$TIMEOUT_CMD" "$WORKER_TIMEOUT" "$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1 | tee "$iter_log" | "$SCRIPT_DIR/watch-filter.py"
|
||||
else
|
||||
"$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1 | tee "$iter_log" | "$SCRIPT_DIR/watch-filter.py"
|
||||
fi
|
||||
claude_rc=${PIPESTATUS[0]}
|
||||
# Log contains stream-json; verdict/promise extraction handled by fallback logic
|
||||
claude_out="$(cat "$iter_log")"
|
||||
else
|
||||
# Default: quiet mode
|
||||
if [[ -n "$TIMEOUT_CMD" ]]; then
|
||||
claude_out="$("$TIMEOUT_CMD" "$WORKER_TIMEOUT" "$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1)"
|
||||
else
|
||||
claude_out="$("$CLAUDE_BIN" "${claude_args[@]}" "$prompt" 2>&1)"
|
||||
fi
|
||||
claude_rc=$?
|
||||
printf '%s\n' "$claude_out" > "$iter_log"
|
||||
fi
|
||||
set -e
|
||||
|
||||
# Handle timeout (exit code 124 from timeout command)
|
||||
worker_timeout=0
|
||||
if [[ -n "$TIMEOUT_CMD" && "$claude_rc" -eq 124 ]]; then
|
||||
echo "ralph: worker timed out after ${WORKER_TIMEOUT}s" >> "$iter_log"
|
||||
log "worker timeout after ${WORKER_TIMEOUT}s"
|
||||
worker_timeout=1
|
||||
fi
|
||||
|
||||
log "claude rc=$claude_rc log=$iter_log"
|
||||
|
||||
force_retry=$worker_timeout
|
||||
plan_review_status=""
|
||||
task_status=""
|
||||
if [[ "$status" == "plan" && ( "$PLAN_REVIEW" == "rp" || "$PLAN_REVIEW" == "codex" ) ]]; then
|
||||
if ! verify_receipt "$REVIEW_RECEIPT_PATH" "plan_review" "$epic_id"; then
|
||||
echo "ralph: missing plan review receipt; forcing retry" >> "$iter_log"
|
||||
log "missing plan receipt; forcing retry"
|
||||
"$FLOWCTL" epic set-plan-review-status "$epic_id" --status needs_work --json >/dev/null 2>&1 || true
|
||||
force_retry=1
|
||||
fi
|
||||
epic_json="$("$FLOWCTL" show "$epic_id" --json 2>/dev/null || true)"
|
||||
plan_review_status="$(json_get plan_review_status "$epic_json")"
|
||||
fi
|
||||
if [[ "$status" == "work" && ( "$WORK_REVIEW" == "rp" || "$WORK_REVIEW" == "codex" ) ]]; then
|
||||
if ! verify_receipt "$REVIEW_RECEIPT_PATH" "impl_review" "$task_id"; then
|
||||
echo "ralph: missing impl review receipt; forcing retry" >> "$iter_log"
|
||||
log "missing impl receipt; forcing retry"
|
||||
force_retry=1
|
||||
fi
|
||||
fi
|
||||
|
||||
# Extract verdict/promise for progress log (not displayed in UI)
|
||||
# In watch mode, parse stream-json to get assistant text; otherwise use raw output
|
||||
if [[ -n "$WATCH_MODE" ]]; then
|
||||
claude_text="$(extract_text_from_stream_json "$iter_log")"
|
||||
else
|
||||
claude_text="$claude_out"
|
||||
fi
|
||||
verdict="$(printf '%s' "$claude_text" | extract_tag verdict)"
|
||||
promise="$(printf '%s' "$claude_text" | extract_tag promise)"
|
||||
|
||||
# Fallback: derive verdict from flowctl status for logging
|
||||
if [[ -z "$verdict" && -n "$plan_review_status" ]]; then
|
||||
case "$plan_review_status" in
|
||||
ship) verdict="SHIP" ;;
|
||||
needs_work) verdict="NEEDS_WORK" ;;
|
||||
esac
|
||||
fi
|
||||
|
||||
if [[ "$status" == "work" ]]; then
|
||||
task_json="$("$FLOWCTL" show "$task_id" --json 2>/dev/null || true)"
|
||||
task_status="$(json_get status "$task_json")"
|
||||
if [[ "$task_status" != "done" ]]; then
|
||||
echo "ralph: task not done; forcing retry" >> "$iter_log"
|
||||
log "task $task_id status=$task_status; forcing retry"
|
||||
force_retry=1
|
||||
else
|
||||
ui_task_done "$task_id"
|
||||
# Derive verdict from task completion for logging
|
||||
[[ -z "$verdict" ]] && verdict="SHIP"
|
||||
fi
|
||||
fi
|
||||
append_progress "$verdict" "$promise" "$plan_review_status" "$task_status"
|
||||
|
||||
if echo "$claude_text" | grep -q "<promise>COMPLETE</promise>"; then
|
||||
ui_complete
|
||||
echo "<promise>COMPLETE</promise>"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
exit_code=0
|
||||
if echo "$claude_text" | grep -q "<promise>FAIL</promise>"; then
|
||||
exit_code=1
|
||||
elif echo "$claude_text" | grep -q "<promise>RETRY</promise>"; then
|
||||
exit_code=2
|
||||
elif [[ "$force_retry" == "1" ]]; then
|
||||
exit_code=2
|
||||
elif [[ "$claude_rc" -ne 0 && "$task_status" != "done" && "$verdict" != "SHIP" ]]; then
|
||||
# Only fail on non-zero exit code if task didn't complete and verdict isn't SHIP
|
||||
# This prevents false failures from transient errors (telemetry, model fallback, etc.)
|
||||
exit_code=1
|
||||
fi
|
||||
|
||||
if [[ "$exit_code" -eq 1 ]]; then
|
||||
log "exit=fail"
|
||||
ui_fail "Claude returned FAIL promise"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ "$exit_code" -eq 2 && "$status" == "work" ]]; then
|
||||
attempts="$(bump_attempts "$ATTEMPTS_FILE" "$task_id")"
|
||||
log "retry task=$task_id attempts=$attempts"
|
||||
ui_retry "$task_id" "$attempts" "$MAX_ATTEMPTS_PER_TASK"
|
||||
if (( attempts >= MAX_ATTEMPTS_PER_TASK )); then
|
||||
reason_file="$RUN_DIR/block-${task_id}.md"
|
||||
{
|
||||
echo "Auto-blocked after ${attempts} attempts."
|
||||
echo "Run: $RUN_ID"
|
||||
echo "Task: $task_id"
|
||||
echo ""
|
||||
echo "Last output:"
|
||||
tail -n 40 "$iter_log" || true
|
||||
} > "$reason_file"
|
||||
"$FLOWCTL" block "$task_id" --reason-file "$reason_file" --json || true
|
||||
ui_blocked "$task_id"
|
||||
fi
|
||||
fi
|
||||
|
||||
sleep 2
|
||||
iter=$((iter + 1))
|
||||
done
|
||||
|
||||
ui_fail "Max iterations ($MAX_ITERATIONS) reached"
|
||||
echo "ralph: max iterations reached" >&2
|
||||
exit 1
|
||||
9
scripts/ralph/ralph_once.sh
Executable file
9
scripts/ralph/ralph_once.sh
Executable file
@@ -0,0 +1,9 @@
|
||||
#!/usr/bin/env bash
|
||||
# Human-in-the-loop Ralph: runs exactly one iteration
|
||||
# Use this to observe behavior before going fully autonomous
|
||||
|
||||
set -euo pipefail
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
|
||||
export MAX_ITERATIONS=1
|
||||
exec "$SCRIPT_DIR/ralph.sh" "$@"
|
||||
230
scripts/ralph/watch-filter.py
Executable file
230
scripts/ralph/watch-filter.py
Executable file
@@ -0,0 +1,230 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Watch filter for Ralph - parses Claude's stream-json output and shows key events.
|
||||
|
||||
Reads JSON lines from stdin, outputs formatted tool calls in TUI style.
|
||||
|
||||
CRITICAL: This filter is "fail open" - if output breaks, it continues draining
|
||||
stdin to prevent SIGPIPE cascading to upstream processes (tee, claude).
|
||||
|
||||
Usage:
|
||||
watch-filter.py # Show tool calls only
|
||||
watch-filter.py --verbose # Show tool calls + thinking + text responses
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
from typing import Optional
|
||||
|
||||
# Global flag to disable output on pipe errors (fail open pattern)
|
||||
_output_disabled = False
|
||||
|
||||
# ANSI color codes (match ralph.sh TUI)
|
||||
if sys.stdout.isatty() and not os.environ.get("NO_COLOR"):
|
||||
C_RESET = "\033[0m"
|
||||
C_DIM = "\033[2m"
|
||||
C_CYAN = "\033[36m"
|
||||
else:
|
||||
C_RESET = C_DIM = C_CYAN = ""
|
||||
|
||||
# TUI indentation (3 spaces to match ralph.sh)
|
||||
INDENT = " "
|
||||
|
||||
# Tool icons
|
||||
ICONS = {
|
||||
"Bash": "🔧",
|
||||
"Edit": "📝",
|
||||
"Write": "📄",
|
||||
"Read": "📖",
|
||||
"Grep": "🔍",
|
||||
"Glob": "📁",
|
||||
"Task": "🤖",
|
||||
"WebFetch": "🌐",
|
||||
"WebSearch": "🔎",
|
||||
"TodoWrite": "📋",
|
||||
"AskUserQuestion": "❓",
|
||||
"Skill": "⚡",
|
||||
}
|
||||
|
||||
|
||||
def safe_print(msg: str) -> None:
|
||||
"""Print that fails open - disables output on BrokenPipe instead of crashing."""
|
||||
global _output_disabled
|
||||
if _output_disabled:
|
||||
return
|
||||
try:
|
||||
print(msg, flush=True)
|
||||
except BrokenPipeError:
|
||||
_output_disabled = True
|
||||
|
||||
|
||||
def drain_stdin() -> None:
|
||||
"""Consume remaining stdin to prevent SIGPIPE to upstream processes."""
|
||||
try:
|
||||
for _ in sys.stdin:
|
||||
pass
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
def truncate(s: str, max_len: int = 60) -> str:
|
||||
s = s.replace("\n", " ").strip()
|
||||
if len(s) > max_len:
|
||||
return s[: max_len - 3] + "..."
|
||||
return s
|
||||
|
||||
|
||||
def format_tool_use(tool_name: str, tool_input: dict) -> str:
|
||||
"""Format a tool use event for TUI display."""
|
||||
icon = ICONS.get(tool_name, "🔹")
|
||||
|
||||
if tool_name == "Bash":
|
||||
cmd = tool_input.get("command", "")
|
||||
desc = tool_input.get("description", "")
|
||||
if desc:
|
||||
return f"{icon} Bash: {truncate(desc)}"
|
||||
return f"{icon} Bash: {truncate(cmd, 60)}"
|
||||
|
||||
elif tool_name == "Edit":
|
||||
path = tool_input.get("file_path", "")
|
||||
return f"{icon} Edit: {path.split('/')[-1] if path else 'unknown'}"
|
||||
|
||||
elif tool_name == "Write":
|
||||
path = tool_input.get("file_path", "")
|
||||
return f"{icon} Write: {path.split('/')[-1] if path else 'unknown'}"
|
||||
|
||||
elif tool_name == "Read":
|
||||
path = tool_input.get("file_path", "")
|
||||
return f"{icon} Read: {path.split('/')[-1] if path else 'unknown'}"
|
||||
|
||||
elif tool_name == "Grep":
|
||||
pattern = tool_input.get("pattern", "")
|
||||
return f"{icon} Grep: {truncate(pattern, 40)}"
|
||||
|
||||
elif tool_name == "Glob":
|
||||
pattern = tool_input.get("pattern", "")
|
||||
return f"{icon} Glob: {pattern}"
|
||||
|
||||
elif tool_name == "Task":
|
||||
desc = tool_input.get("description", "")
|
||||
agent = tool_input.get("subagent_type", "")
|
||||
return f"{icon} Task ({agent}): {truncate(desc, 50)}"
|
||||
|
||||
elif tool_name == "Skill":
|
||||
skill = tool_input.get("skill", "")
|
||||
return f"{icon} Skill: {skill}"
|
||||
|
||||
elif tool_name == "TodoWrite":
|
||||
todos = tool_input.get("todos", [])
|
||||
in_progress = [t for t in todos if t.get("status") == "in_progress"]
|
||||
if in_progress:
|
||||
return f"{icon} Todo: {truncate(in_progress[0].get('content', ''))}"
|
||||
return f"{icon} Todo: {len(todos)} items"
|
||||
|
||||
else:
|
||||
return f"{icon} {tool_name}"
|
||||
|
||||
|
||||
def format_tool_result(block: dict) -> Optional[str]:
|
||||
"""Format a tool_result block (errors only).
|
||||
|
||||
Args:
|
||||
block: The full tool_result block (not just content)
|
||||
"""
|
||||
# Check is_error on the block itself
|
||||
if block.get("is_error"):
|
||||
content = block.get("content", "")
|
||||
error_text = str(content) if content else "unknown error"
|
||||
return f"{INDENT}{C_DIM}❌ {truncate(error_text, 60)}{C_RESET}"
|
||||
|
||||
# Also check content for error strings (heuristic)
|
||||
content = block.get("content", "")
|
||||
if isinstance(content, str):
|
||||
lower = content.lower()
|
||||
if "error" in lower or "failed" in lower:
|
||||
return f"{INDENT}{C_DIM}⚠️ {truncate(content, 60)}{C_RESET}"
|
||||
|
||||
return None
|
||||
|
||||
|
||||
def process_event(event: dict, verbose: bool) -> None:
|
||||
"""Process a single stream-json event."""
|
||||
event_type = event.get("type", "")
|
||||
|
||||
# Tool use events (assistant messages)
|
||||
if event_type == "assistant":
|
||||
message = event.get("message", {})
|
||||
content = message.get("content", [])
|
||||
|
||||
for block in content:
|
||||
block_type = block.get("type", "")
|
||||
|
||||
if block_type == "tool_use":
|
||||
tool_name = block.get("name", "")
|
||||
tool_input = block.get("input", {})
|
||||
formatted = format_tool_use(tool_name, tool_input)
|
||||
safe_print(f"{INDENT}{C_DIM}{formatted}{C_RESET}")
|
||||
|
||||
elif verbose and block_type == "text":
|
||||
text = block.get("text", "")
|
||||
if text.strip():
|
||||
safe_print(f"{INDENT}{C_CYAN}💬 {text}{C_RESET}")
|
||||
|
||||
elif verbose and block_type == "thinking":
|
||||
thinking = block.get("thinking", "")
|
||||
if thinking.strip():
|
||||
safe_print(f"{INDENT}{C_DIM}🧠 {truncate(thinking, 100)}{C_RESET}")
|
||||
|
||||
# Tool results (user messages with tool_result blocks)
|
||||
elif event_type == "user":
|
||||
message = event.get("message", {})
|
||||
content = message.get("content", [])
|
||||
|
||||
for block in content:
|
||||
if block.get("type") == "tool_result":
|
||||
formatted = format_tool_result(block)
|
||||
if formatted:
|
||||
safe_print(formatted)
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description="Filter Claude stream-json output")
|
||||
parser.add_argument(
|
||||
"--verbose",
|
||||
action="store_true",
|
||||
help="Show text and thinking in addition to tool calls",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
for line in sys.stdin:
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
|
||||
try:
|
||||
event = json.loads(line)
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
|
||||
try:
|
||||
process_event(event, args.verbose)
|
||||
except Exception:
|
||||
# Swallow processing errors - keep draining stdin
|
||||
pass
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except KeyboardInterrupt:
|
||||
sys.exit(0)
|
||||
except BrokenPipeError:
|
||||
# Output broken but keep draining to prevent upstream SIGPIPE
|
||||
drain_stdin()
|
||||
sys.exit(0)
|
||||
except Exception as e:
|
||||
print(f"watch-filter: {e}", file=sys.stderr)
|
||||
drain_stdin()
|
||||
sys.exit(0)
|
||||
64
server/reflector/views/transcripts_chat.py
Normal file
64
server/reflector/views/transcripts_chat.py
Normal file
@@ -0,0 +1,64 @@
|
||||
"""
|
||||
Transcripts chat API
|
||||
====================
|
||||
|
||||
WebSocket endpoint for bidirectional chat with LLM about transcript content.
|
||||
"""
|
||||
|
||||
from typing import Optional
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, WebSocket, WebSocketDisconnect
|
||||
|
||||
import reflector.auth as auth
|
||||
from reflector.db.recordings import recordings_controller
|
||||
from reflector.db.transcripts import transcripts_controller
|
||||
from reflector.utils.transcript_formats import topics_to_webvtt_named
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
async def _get_is_multitrack(transcript) -> bool:
|
||||
"""Detect if transcript is from multitrack recording."""
|
||||
if not transcript.recording_id:
|
||||
return False
|
||||
recording = await recordings_controller.get_by_id(transcript.recording_id)
|
||||
return recording is not None and recording.is_multitrack
|
||||
|
||||
|
||||
@router.websocket("/transcripts/{transcript_id}/chat")
|
||||
async def transcript_chat_websocket(
|
||||
transcript_id: str,
|
||||
websocket: WebSocket,
|
||||
user: Optional[auth.UserInfo] = Depends(auth.current_user_optional),
|
||||
):
|
||||
"""WebSocket endpoint for chatting with LLM about transcript content."""
|
||||
# 1. Auth check
|
||||
user_id = user["sub"] if user else None
|
||||
transcript = await transcripts_controller.get_by_id_for_http(
|
||||
transcript_id, user_id=user_id
|
||||
)
|
||||
if not transcript:
|
||||
raise HTTPException(status_code=404, detail="Transcript not found")
|
||||
|
||||
# 2. Accept connection
|
||||
await websocket.accept()
|
||||
|
||||
# 3. Generate WebVTT context
|
||||
is_multitrack = await _get_is_multitrack(transcript)
|
||||
webvtt = topics_to_webvtt_named(
|
||||
transcript.topics, transcript.participants, is_multitrack
|
||||
)
|
||||
|
||||
try:
|
||||
# 4. Message loop
|
||||
while True:
|
||||
data = await websocket.receive_json()
|
||||
|
||||
if data.get("type") == "get_context":
|
||||
# Return WebVTT context
|
||||
await websocket.send_json({"type": "context", "webvtt": webvtt})
|
||||
else:
|
||||
# Echo for now (backward compatibility)
|
||||
await websocket.send_json({"type": "echo", "data": data})
|
||||
except WebSocketDisconnect:
|
||||
pass
|
||||
157
server/tests/test_transcripts_chat.py
Normal file
157
server/tests/test_transcripts_chat.py
Normal file
@@ -0,0 +1,157 @@
|
||||
"""Tests for transcript chat WebSocket endpoint."""
|
||||
|
||||
import pytest
|
||||
|
||||
from reflector.db.transcripts import (
|
||||
SourceKind,
|
||||
TranscriptParticipant,
|
||||
TranscriptTopic,
|
||||
transcripts_controller,
|
||||
)
|
||||
from reflector.processors.types import Word
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
async def test_transcript(setup_database):
|
||||
"""Create a test transcript for WebSocket tests."""
|
||||
transcript = await transcripts_controller.add(
|
||||
name="Test Transcript for Chat", source_kind=SourceKind.FILE
|
||||
)
|
||||
return transcript
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
async def test_transcript_with_content(setup_database):
|
||||
"""Create a test transcript with actual content for WebVTT generation."""
|
||||
transcript = await transcripts_controller.add(
|
||||
name="Test Transcript with Content", source_kind=SourceKind.FILE
|
||||
)
|
||||
|
||||
# Add participants
|
||||
await transcripts_controller.update(
|
||||
transcript,
|
||||
{
|
||||
"participants": [
|
||||
TranscriptParticipant(id="1", speaker=0, name="Alice").model_dump(),
|
||||
TranscriptParticipant(id="2", speaker=1, name="Bob").model_dump(),
|
||||
]
|
||||
},
|
||||
)
|
||||
|
||||
# Add topic with words
|
||||
await transcripts_controller.upsert_topic(
|
||||
transcript,
|
||||
TranscriptTopic(
|
||||
title="Introduction",
|
||||
summary="Opening remarks",
|
||||
timestamp=0.0,
|
||||
words=[
|
||||
Word(text="Hello ", start=0.0, end=1.0, speaker=0),
|
||||
Word(text="everyone.", start=1.0, end=2.0, speaker=0),
|
||||
Word(text="Hi ", start=2.0, end=3.0, speaker=1),
|
||||
Word(text="there!", start=3.0, end=4.0, speaker=1),
|
||||
],
|
||||
),
|
||||
)
|
||||
|
||||
return transcript
|
||||
|
||||
|
||||
def test_chat_websocket_connection_success(test_transcript):
|
||||
"""Test successful WebSocket connection to chat endpoint."""
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
from reflector.app import app
|
||||
|
||||
with TestClient(app) as client:
|
||||
# Connect to WebSocket endpoint
|
||||
with client.websocket_connect(
|
||||
f"/v1/transcripts/{test_transcript.id}/chat"
|
||||
) as websocket:
|
||||
# Send a test message
|
||||
websocket.send_json({"type": "message", "text": "Hello"})
|
||||
|
||||
# Receive echo response
|
||||
response = websocket.receive_json()
|
||||
assert response["type"] == "echo"
|
||||
assert response["data"]["type"] == "message"
|
||||
assert response["data"]["text"] == "Hello"
|
||||
|
||||
|
||||
def test_chat_websocket_nonexistent_transcript():
|
||||
"""Test WebSocket connection fails for nonexistent transcript."""
|
||||
from starlette.testclient import TestClient
|
||||
from starlette.websockets import WebSocketDisconnect
|
||||
|
||||
from reflector.app import app
|
||||
|
||||
with TestClient(app) as client:
|
||||
# Try to connect to non-existent transcript - should raise on connect
|
||||
with pytest.raises(WebSocketDisconnect):
|
||||
with client.websocket_connect(
|
||||
"/v1/transcripts/nonexistent-id/chat"
|
||||
) as websocket:
|
||||
websocket.send_json({"type": "message", "text": "Hello"})
|
||||
|
||||
|
||||
def test_chat_websocket_multiple_messages(test_transcript):
|
||||
"""Test sending multiple messages through WebSocket."""
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
from reflector.app import app
|
||||
|
||||
with TestClient(app) as client:
|
||||
with client.websocket_connect(
|
||||
f"/v1/transcripts/{test_transcript.id}/chat"
|
||||
) as websocket:
|
||||
# Send multiple messages
|
||||
messages = ["First message", "Second message", "Third message"]
|
||||
|
||||
for msg in messages:
|
||||
websocket.send_json({"type": "message", "text": msg})
|
||||
response = websocket.receive_json()
|
||||
assert response["type"] == "echo"
|
||||
assert response["data"]["text"] == msg
|
||||
|
||||
|
||||
def test_chat_websocket_disconnect_graceful(test_transcript):
|
||||
"""Test WebSocket disconnects gracefully."""
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
from reflector.app import app
|
||||
|
||||
with TestClient(app) as client:
|
||||
with client.websocket_connect(
|
||||
f"/v1/transcripts/{test_transcript.id}/chat"
|
||||
) as websocket:
|
||||
websocket.send_json({"type": "message", "text": "Hello"})
|
||||
websocket.receive_json()
|
||||
# Close connection - context manager handles it
|
||||
# No exception should be raised
|
||||
|
||||
|
||||
def test_chat_websocket_context_generation(test_transcript_with_content):
|
||||
"""Test WebVTT context is generated on connection."""
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
from reflector.app import app
|
||||
|
||||
with TestClient(app) as client:
|
||||
with client.websocket_connect(
|
||||
f"/v1/transcripts/{test_transcript_with_content.id}/chat"
|
||||
) as websocket:
|
||||
# Send request for context (new message type)
|
||||
websocket.send_json({"type": "get_context"})
|
||||
|
||||
# Receive context response
|
||||
response = websocket.receive_json()
|
||||
assert response["type"] == "context"
|
||||
assert "webvtt" in response
|
||||
|
||||
# Verify WebVTT format
|
||||
webvtt = response["webvtt"]
|
||||
assert webvtt.startswith("WEBVTT")
|
||||
assert "<v Alice>" in webvtt
|
||||
assert "<v Bob>" in webvtt
|
||||
assert "Hello everyone." in webvtt
|
||||
assert "Hi there!" in webvtt
|
||||
Reference in New Issue
Block a user