Add MUCA

README.md

@@ -39,6 +39,27 @@ when the container restarts, the room is empty again.
   Python stage installs the backend deps, copies the built assets in,
   and runs `uvicorn`.
 
+## Optional: the always-online chat agent (MUCA)
+
+If `OPENAI_API_KEY` is set in the container environment, a small
+LLM-backed participant — the **M**ulti-**U**ser **C**hat **A**gent —
+joins the room by default. It keeps a short rolling buffer of recent
+messages and, after each human message, makes a single OpenAI call to
+decide whether to respond. The default personality is intentionally
+restrained: it stays quiet most of the time.
+
+| Variable             | Default       | Purpose                                  |
+| -------------------- | ------------- | ---------------------------------------- |
+| `OPENAI_API_KEY`     | _(unset)_     | **Required** to enable the MUCA.         |
+| `MUCA_NAME`          | `muca`        | Display name in the roster.              |
+| `MUCA_SYSTEM_PROMPT` | _(built-in)_  | Personality / instructions.              |
+| `MUCA_MODEL`         | `gpt-4o-mini` | OpenAI chat model.                       |
+| `MUCA_BUFFER_SIZE`   | `30`          | Max messages kept as context (2..200).   |
+
+On Hugging Face Spaces, set these as Space *secrets* (for the API key)
+and *variables* (for the rest). See `backend/README.md` for the design
+notes.
+
 ## Run with Docker (matches the HF Space build)
 
 ```bash

backend/README.md

@@ -34,6 +34,33 @@ If the requested username collides with an existing one the server picks
 `name-2`, `name-3`, ... and tells the client which name was actually
 assigned in the `welcome` frame.
 
+## MUCA — the Multi-User Chat Agent
+
+If `OPENAI_API_KEY` is set, an LLM-backed participant joins the room as
+a permanent member. It keeps a small rolling buffer of recent messages
+and, after each *human* message, makes a single LLM call to decide
+whether to respond — the default system prompt asks it to mostly stay
+quiet so the chatroom doesn't feel like a chatbot demo.
+
+| Variable             | Default      | Purpose                                                                 |
+| -------------------- | ------------ | ----------------------------------------------------------------------- |
+| `OPENAI_API_KEY`     | _(unset)_    | **Required** to enable the MUCA. Without it the room runs as before.    |
+| `MUCA_NAME`          | `muca`       | The agent's display name in the roster and message history.             |
+| `MUCA_SYSTEM_PROMPT` | _(built-in restraint prompt)_ | Personality / instructions. The "reply as JSON" protocol bit is appended automatically. |
+| `MUCA_MODEL`         | `gpt-5-nano` | OpenAI chat-completions model used for both the judgment and the reply. |
+| `MUCA_BUFFER_SIZE`   | `30`         | Max messages of history kept as context (clamped to 2..200).            |
+
+Implementation notes:
+
+* Only one judgment / generation is ever in-flight. Triggers that
+  arrive while the agent is "thinking" are coalesced — at most one
+  follow-up pass runs after the current one finishes.
+* The agent observes its own messages so it doesn't re-greet or repeat
+  itself, but only *human* messages trigger a fresh judgment (otherwise
+  it would talk to itself in a loop).
+* The agent name is reserved in the roster: a real user requesting the
+  same name gets the usual `name-2`, `name-3`, ... suffix.
+
 ## Running locally
 
 ```bash
@@ -43,5 +70,7 @@ pip install -r requirements.txt
 # Point at the locally built frontend (optional). Without this, only the
 # API is served.
 export YAP_STATIC_DIR=../frontend/dist
+# Optional: enable the MUCA.
+export OPENAI_API_KEY=sk-...
 uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload
 ```

backend/app/main.py

@@ -7,6 +7,10 @@ A FastAPI application that serves:
 
 A single uvicorn process serves the entire application, which keeps the
 Hugging Face Space image simple.
+
+If ``OPENAI_API_KEY`` is set in the environment, an LLM-backed
+participant (the MUCA — Multi-User Chat Agent) joins the room as a
+permanent member. See ``app/muca.py`` for details.
 """
 
 from __future__ import annotations
@@ -17,12 +21,14 @@ import os
 from contextlib import asynccontextmanager
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any
+from typing import Any, Awaitable, Callable
 
 from fastapi import FastAPI, WebSocket, WebSocketDisconnect
 from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 
+from app.muca import MucaAgent, MucaConfig
+
 logger = logging.getLogger("yap")
 logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
 
@@ -32,21 +38,43 @@ logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name
 STATIC_DIR = Path(os.environ.get("YAP_STATIC_DIR", "/app/static")).resolve()
 
 
+MessageObserver = Callable[[str, str], Awaitable[None]]
+
+
 class ChatRoom:
     """In-memory broadcast hub for a single chat room.
 
     Yap Space is intentionally ephemeral: nothing is persisted, and once
     the process restarts the room is empty again. This matches the
     "your yap eventually meets the void" pitch in the README.
+
+    The room also supports two extension points used by the MUCA:
+
+    * ``add_virtual_member(name)`` registers a participant that has no
+      WebSocket of its own but should still appear in the roster.
+    * ``add_message_observer(fn)`` subscribes a coroutine that gets
+      called with ``(author, text)`` after every chat message. The
+      MUCA uses this to update its context buffer and decide whether
+      to respond.
+    * ``post(name, text)`` lets a virtual member broadcast a message
+      as if they were a real client.
     """
 
     def __init__(self) -> None:
         self._members: dict[WebSocket, str] = {}
+        self._virtual_members: set[str] = set()
+        self._observers: list[MessageObserver] = []
         self._lock = asyncio.Lock()
 
     @property
     def usernames(self) -> list[str]:
-        return sorted(self._members.values())
+        return sorted(set(self._members.values()) | self._virtual_members)
+
+    def add_virtual_member(self, name: str) -> None:
+        self._virtual_members.add(name)
+
+    def add_message_observer(self, observer: MessageObserver) -> None:
+        self._observers.append(observer)
 
     async def join(self, websocket: WebSocket, username: str) -> str:
         username = self._unique_name(username)
@@ -70,19 +98,19 @@ class ChatRoom:
         text = text.strip()
         if not text:
             return
-        await self._broadcast(
-            {
-                "type": "message",
-                "username": username,
-                "text": text[:2000],
-                "timestamp": _now_iso(),
-            }
-        )
+        await self._publish_message(username, text)
+
+    async def post(self, username: str, text: str) -> None:
+        """Broadcast a message as a virtual (non-WebSocket) member."""
+        text = text.strip()
+        if not text:
+            return
+        await self._publish_message(username, text)
 
     def _unique_name(self, requested: str) -> str:
         base = requested.strip() or "anon"
         base = base[:32]
-        existing = set(self._members.values())
+        existing = set(self._members.values()) | self._virtual_members
         if base not in existing:
             return base
         suffix = 2
@@ -90,6 +118,22 @@ class ChatRoom:
             suffix += 1
         return f"{base}-{suffix}"
 
+    async def _publish_message(self, username: str, text: str) -> None:
+        text = text[:2000]
+        await self._broadcast(
+            {
+                "type": "message",
+                "username": username,
+                "text": text,
+                "timestamp": _now_iso(),
+            }
+        )
+        for observer in self._observers:
+            try:
+                await observer(username, text)
+            except Exception:  # noqa: BLE001 - never let an observer break broadcasting
+                logger.exception("Message observer raised")
+
     async def _broadcast(self, payload: dict[str, Any]) -> None:
         # Snapshot to avoid mutating the dict while iterating.
         async with self._lock:
@@ -116,11 +160,50 @@ def _now_iso() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
+def _attach_muca(room: ChatRoom) -> MucaAgent | None:
+    """Create a MUCA from environment config and wire it into the room.
+
+    Returns ``None`` when no API key is configured, in which case the
+    backend behaves as a plain chatroom.
+    """
+    config = MucaConfig.from_env()
+    if config is None:
+        logger.info("MUCA disabled (set OPENAI_API_KEY to enable)")
+        return None
+
+    agent = MucaAgent(config, post=room.post)
+    room.add_virtual_member(agent.name)
+
+    async def on_message(author: str, text: str) -> None:
+        # Always feed the buffer so the MUCA has a memory of every
+        # message, including its own. Only trigger a fresh judgment when
+        # a *human* spoke — otherwise the MUCA would keep responding to
+        # itself in a loop.
+        await agent.observe(author, text)
+        if author != agent.name:
+            agent.maybe_respond()
+
+    room.add_message_observer(on_message)
+    logger.info(
+        "MUCA enabled as %r using model %s (buffer=%d)",
+        agent.name,
+        config.model,
+        config.buffer_size,
+    )
+    return agent
+
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    app.state.room = ChatRoom()
+    room = ChatRoom()
+    app.state.room = room
+    app.state.muca = _attach_muca(room)
     logger.info("Yap Space online; static dir=%s", STATIC_DIR)
-    yield
+    try:
+        yield
+    finally:
+        if app.state.muca is not None:
+            await app.state.muca.shutdown()
 
 
 app = FastAPI(title="Yap Space", lifespan=lifespan)
@@ -129,7 +212,13 @@ app = FastAPI(title="Yap Space", lifespan=lifespan)
 @app.get("/api/health")
 async def health() -> JSONResponse:
     room: ChatRoom = app.state.room
-    return JSONResponse({"status": "ok", "users": len(room.usernames)})
+    return JSONResponse(
+        {
+            "status": "ok",
+            "users": len(room.usernames),
+            "muca": app.state.muca.name if app.state.muca else None,
+        }
+    )
 
 
 @app.websocket("/api/ws")

backend/app/muca.py

@@ -0,0 +1,229 @@
+"""Multi-User Chat Agent (MUCA).
+
+A small "always online" participant in the chatroom backed by an LLM.
+
+Design notes
+------------
+
+* The agent keeps a bounded rolling buffer of recent messages so it has
+  some context to reason about, without ever growing unboundedly.
+* After every *human* message the agent decides — via a single LLM call
+  in JSON mode — whether it actually wants to say something. The default
+  system prompt instructs it to stay silent most of the time so the room
+  doesn't feel like a chatbot demo.
+* Only one judgment / generation is ever in-flight. Additional triggers
+  while the agent is "thinking" are coalesced via a `_pending` flag: if
+  any messages arrived during a generation, exactly one more pass runs
+  immediately afterwards. This both prevents the MUCA from spamming and
+  ensures we don't drop a trigger that arrived mid-flight.
+* The module is self-contained: if `OPENAI_API_KEY` is unset, no MUCA is
+  created and the rest of the backend behaves exactly as before.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from collections import deque
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Deque
+
+from openai import AsyncOpenAI
+
+logger = logging.getLogger("yap.muca")
+
+DEFAULT_NAME = "muca"
+DEFAULT_MODEL = "gpt-5-nano"
+DEFAULT_BUFFER_SIZE = 30
+DEFAULT_SYSTEM_PROMPT = (
+    "You are a quiet, thoughtful participant in a casual group chat. "
+    "Most of the time you just listen. Speak only when you genuinely "
+    "have something useful, curious, or in-character to add. Avoid "
+    "responding to every message. Avoid greeting people you've already "
+    "greeted. Keep replies short and conversational."
+)
+
+# Appended to whatever system prompt the operator configured. This part
+# is non-negotiable because it defines the wire protocol the rest of the
+# code depends on.
+_PROTOCOL_SUFFIX = (
+    'You will be shown the most recent chatroom messages and must reply '
+    'with a single JSON object and nothing else. Use '
+    '{{"respond": true, "message": "<your message>"}} to speak, or '
+    '{{"respond": false}} to stay silent. Stay silent by default — only '
+    "speak when it's clearly worth it. Your name in the room is "
+    '"{name}". Do not prefix your message with your own name.'
+)
+
+
+PostFn = Callable[[str, str], Awaitable[None]]
+
+
+@dataclass(frozen=True)
+class MucaConfig:
+    api_key: str
+    name: str = DEFAULT_NAME
+    system_prompt: str = DEFAULT_SYSTEM_PROMPT
+    model: str = DEFAULT_MODEL
+    buffer_size: int = DEFAULT_BUFFER_SIZE
+
+    @classmethod
+    def from_env(cls) -> "MucaConfig | None":
+        """Build a config from environment variables.
+
+        Returns ``None`` when ``OPENAI_API_KEY`` is unset, which is the
+        signal to disable the MUCA entirely.
+        """
+        api_key = os.environ.get("OPENAI_API_KEY", "").strip()
+        if not api_key:
+            return None
+
+        name = os.environ.get("MUCA_NAME", "").strip() or DEFAULT_NAME
+        system_prompt = (
+            os.environ.get("MUCA_SYSTEM_PROMPT", "").strip() or DEFAULT_SYSTEM_PROMPT
+        )
+        model = os.environ.get("MUCA_MODEL", "").strip() or DEFAULT_MODEL
+
+        try:
+            buffer_size = int(os.environ.get("MUCA_BUFFER_SIZE", DEFAULT_BUFFER_SIZE))
+        except ValueError:
+            buffer_size = DEFAULT_BUFFER_SIZE
+        buffer_size = max(2, min(buffer_size, 200))
+
+        return cls(
+            api_key=api_key,
+            name=name[:32],
+            system_prompt=system_prompt,
+            model=model,
+            buffer_size=buffer_size,
+        )
+
+
+@dataclass
+class _BufferedMessage:
+    author: str
+    text: str
+
+
+class MucaAgent:
+    """An LLM-backed participant in the chatroom."""
+
+    def __init__(self, config: MucaConfig, post: PostFn) -> None:
+        self.config = config
+        self._post = post
+        self._client = AsyncOpenAI(api_key=config.api_key)
+        self._buffer: Deque[_BufferedMessage] = deque(maxlen=config.buffer_size)
+        self._buffer_lock = asyncio.Lock()
+        self._task: asyncio.Task[None] | None = None
+        # Set whenever a fresh trigger arrives. The judgment loop drains
+        # this flag every iteration; if it's still set after a pass, we
+        # immediately run another one.
+        self._pending = False
+
+    @property
+    def name(self) -> str:
+        return self.config.name
+
+    async def observe(self, author: str, text: str) -> None:
+        """Record a message in the rolling context buffer.
+
+        Both human messages and the MUCA's own messages should be
+        observed so the agent has a memory of what it has already said.
+        """
+        text = text.strip()
+        if not text:
+            return
+        async with self._buffer_lock:
+            self._buffer.append(_BufferedMessage(author=author, text=text))
+
+    def maybe_respond(self) -> None:
+        """Signal that the agent should consider responding.
+
+        Cheap and non-blocking — call this after every *human* message
+        (not after the agent's own messages, otherwise it will talk to
+        itself forever).
+        """
+        self._pending = True
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(self._loop())
+
+    async def shutdown(self) -> None:
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            except Exception:  # noqa: BLE001
+                logger.exception("MUCA task raised during shutdown")
+
+    async def _loop(self) -> None:
+        # Drain triggers until the buffer hasn't changed since the last
+        # decision. New triggers that arrive *during* a decision flip
+        # `_pending` back on so we run one more pass.
+        while self._pending:
+            self._pending = False
+            try:
+                await self._consider_and_respond()
+            except Exception:  # noqa: BLE001
+                logger.exception("MUCA judgment loop failed")
+
+    async def _consider_and_respond(self) -> None:
+        async with self._buffer_lock:
+            history = list(self._buffer)
+
+        decision = await self._ask_llm(history)
+        if decision is None:
+            return
+        message = decision.strip()
+        if not message:
+            return
+        # Cap to the same length the WebSocket handler enforces for users.
+        await self._post(self.name, message[:2000])
+
+    async def _ask_llm(self, history: list[_BufferedMessage]) -> str | None:
+        system_content = (
+            f"{self.config.system_prompt}\n\n"
+            + _PROTOCOL_SUFFIX.format(name=self.config.name)
+        )
+        transcript = "\n".join(f"{m.author}: {m.text}" for m in history)
+        if not transcript:
+            transcript = "(no messages yet)"
+        user_content = (
+            "Recent chatroom messages (oldest first):\n\n"
+            f"{transcript}\n\n"
+            "Reply with the JSON decision now."
+        )
+
+        try:
+            # Note: we deliberately do not pass `temperature`. Newer
+            # OpenAI models (the o-series and some gpt-5.x variants)
+            # reject any non-default temperature, and the default is
+            # fine for this use case.
+            response = await self._client.chat.completions.create(
+                model=self.config.model,
+                response_format={"type": "json_object"},
+                messages=[
+                    {"role": "system", "content": system_content},
+                    {"role": "user", "content": user_content},
+                ],
+            )
+        except Exception:  # noqa: BLE001 - log and stay silent on any API failure
+            logger.exception("OpenAI request failed; MUCA staying silent")
+            return None
+
+        raw = (response.choices[0].message.content or "").strip()
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            logger.warning("MUCA returned non-JSON response: %r", raw[:200])
+            return None
+
+        if not isinstance(payload, dict) or not payload.get("respond"):
+            return None
+        message = payload.get("message")
+        if not isinstance(message, str):
+            return None
+        return message

backend/requirements.txt

@@ -1,3 +1,4 @@
 fastapi==0.115.4
 uvicorn[standard]==0.32.0
 websockets==13.1
+openai==2.33.0