speakeasy/README.md

SpeakEasy: Know who's talking

Client flow

1. Client uploads EPUB
2. Backend:
   • Stores file
   • Creates book_id
   • Publishes job to RabbitMQ
3. Client subscribes:
   • GET /books/{book_id}/stream via WebSocket
4. Backend:
   • Authenticates user
   • Remembers: connection -> book_id
5. Worker processes text:
   • Calls Ollama
   • Stores result in Postgres
   • Emits "result ready" event
6. Backend:
   • Receives event
   • Pushes mathing results to the subscribed client

Example WebSocket message to client

{
    "book_id": "book-abc",
    "paragraph_id": "p-432",
    "speaker": "Mary",
    "confidence": 0.87
}

Worker flow

1. Receives job from RabbitMQ
2. Loads paragraph text
3. Embeds paragraph
4. Queries vector DB (pgvector)
5. Builds prompt with retrieved content
6. Sends prompt to Ollama
7. Stores result