Clamor

Real-time audience thoughts tool for presentations and classrooms. Collective audience thinking, summarized in real-time.

Setup

1. Install dependencies:

uv sync

2. Set up Google Cloud authentication:

gcloud auth application-default login

This uses your Google Cloud project with Vertex AI enabled. Make sure you have:

• A Google Cloud project with Vertex AI API enabled
• Appropriate permissions to use Gemini models

Alternatively, you can set the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to a service account key file.

Running

Start the server:

uv run python app.py

The application will be available at http://localhost:8080

Usage

1. Open http://localhost:8080 in your browser (presenter view)
2. A QR code will be displayed
3. Audience members scan the QR code to submit their thoughts
4. The presenter view automatically updates with AI-generated summaries, clustering similar thoughts together

Architecture

• Backend: FastAPI with Vertex AI Gemini for AI summarization
• Frontend: Vanilla JavaScript with Server-Sent Events for real-time updates
• State: In-memory session management (sessions are lost on restart)

Sequence Diagram

sequenceDiagram
    participant Presenter
    participant Audience
    participant Server
    participant LLM

    Note over Presenter: Session Setup
    Presenter->>Server: POST /api/session {question}
    Server-->>Presenter: {session_id}
    Presenter->>Server: GET /api/qr/{session_id}
    Server-->>Presenter: QR code
    Presenter->>Server: GET /api/stream/{session_id}
    Server-->>Presenter: SSE: connection established

    Note over Audience: Join & Submit
    Audience->>Server: GET /audience/{session_id}
    Server-->>Audience: Page with question
    Audience->>Server: POST /api/feedback {name, thoughts}
    Server-->>Audience: {status: ok}

    Note over Server: Summarization (rate-limited)
    Server->>LLM: Summarize responses
    LLM-->>Server: Themed summary<br>{question, names, thoughts}
    Server-->>Presenter: SSE: summary update

Key Concepts:

1. Server-Sent Events (SSE): The presenter maintains a persistent connection to receive real-time updates. Unlike WebSockets, SSE is unidirectional (server to client) and works over standard HTTP.
2. Rate Limiting: To avoid overwhelming the LLM API, the server waits at least 2 seconds between summarization requests. Multiple submissions within this window are batched together.
3. Session State: Each session stores the question, all feedback submissions, and the current summary. Multiple audience members can submit to the same session.
4. QR Code Flow: The QR code encodes the audience URL, allowing easy mobile access without typing.