feat(setup): add gordie init wizard (#33)

* feat(setup): add gordie init wizard

* test(setup): cover setup cli edge cases

* style(setup): format setup cli

* test(setup): use pytest raises for setup errors

* chore(setup): declare scripts package exports

* feat(setup): reuse existing env values

* feat(setup): default chat media to discord

* feat(setup): link discord credential setup

* fix(setup): link discord bot token page

* fix(setup): run migrations on server startup

* feat(discord): add gateway mode

* fix(setup): start docker services after init

* fix(setup): derive discord mode from hosted flag

* fix(setup): rebuild docker services during init

* refactor(agent): move response delivery to transport handlers

Author: ryanshepps

.env.example

@@ -24,6 +24,26 @@ LLM_MODEL=gpt-4o-mini                   # provider-specific model name
 YAHOO_CLIENT_ID=
 YAHOO_CLIENT_SECRET=
 
+# ----------------------------------------------------------------------------
+# Chat media
+# ----------------------------------------------------------------------------
+CHAT_MEDIA=                             # comma-separated; telegram, discord, email, sms
+
+# ----------------------------------------------------------------------------
+# Telegram (optional; only needed when CHAT_MEDIA includes telegram)
+# ----------------------------------------------------------------------------
+TELEGRAM_BOT_TOKEN=
+
+# ----------------------------------------------------------------------------
+# Discord (optional; only needed when CHAT_MEDIA includes discord)
+# ----------------------------------------------------------------------------
+DISCORD_MODE=gateway                   # gateway for local bot websocket; interactions for public HTTPS endpoint
+DISCORD_APPLICATION_ID=
+DISCORD_PUBLIC_KEY=                    # interactions mode only
+DISCORD_BOT_TOKEN=                     # gateway mode only
+DISCORD_ALLOWED_USER_IDS=              # gateway mode only; comma-separated Discord user IDs
+DISCORD_REQUIRE_MENTION=true           # gateway mode only; ignored in direct messages
+
 # ----------------------------------------------------------------------------
 # Email — Mailgun (optional; server runs without it but cannot send email)
 # ----------------------------------------------------------------------------

Dockerfile

@@ -43,6 +43,7 @@ COPY --from=builder --chown=app:app /app /app
 ENV PATH="/app/.venv/bin:${PATH}" \
     PYTHONUNBUFFERED=1 \
     PYTHONDONTWRITEBYTECODE=1 \
+    GORDIE_LOG_FILE=stderr \
     SERVER_HOST=0.0.0.0 \
     SERVER_PORT=8000
 

README.md

@@ -45,7 +45,7 @@ Real conversations with Gordie.
                 ┌──────────────────────────────────────────┐
    Email ──►    │  Quart HTTP server (server/server.py)    │
    SMS   ──►    │  /email/webhook  /sms/webhook  /callback │
-   Discord ─►   │  /discord/interactions                   │
+   Discord ─►   │  /discord/interactions or Gateway client │
                 └────────────────┬─────────────────────────┘
                                  │
                                  ▼

agent/graph_builder.py

@@ -18,7 +18,7 @@ def build_agent_graph(graph_checkpointer: object | None = checkpointer):
     workflow.add_node("supervisor", supervisor_node)
     workflow.add_node("data_quality", data_quality_node)
     workflow.add_node("voice_rewrite", make_voice_rewrite_node(registry))  # pyright: ignore[reportArgumentType]
-    workflow.add_node("response", make_response_node(registry))  # pyright: ignore[reportArgumentType]
+    workflow.add_node("response", make_response_node())  # pyright: ignore[reportArgumentType]
 
     workflow.set_entry_point("context")
     workflow.add_edge("context", "supervisor")

agent/response_node.py

@@ -1,7 +1,4 @@
-"""Response node for the fantasy sports assistant graph.
-
-Dispatches responses through the configured channel adapter.
-"""
+"""Response node for the fantasy sports assistant graph."""
 
 from collections.abc import Callable, Mapping
 from typing import Literal, cast
@@ -10,9 +7,7 @@
 
 from agent.agent_state import AgentState
 from agent.memory_store import get_memory_store, summarize_and_store_conversation
-from data.models import Medium
 from module.logger import get_logger
-from server.adapters.base import AdapterRegistry
 
 logger = get_logger(__name__)
 
@@ -54,47 +49,16 @@ def _store_conversation_memory(state: AgentState, messages: list[object]) -> Non
             logger.error(f"Failed to store conversation memory: {e}")
 
 
-def _coerce_medium(channel: object) -> Medium | None:
-    if isinstance(channel, Medium):
-        return channel
-    if isinstance(channel, str):
-        try:
-            return Medium(channel)
-        except ValueError:
-            return None
-    return None
-
-
-def make_response_node(
-    registry: AdapterRegistry,
-) -> Callable[[AgentState], Command[Literal["__end__"]]]:
+def make_response_node() -> Callable[[AgentState], Command[Literal["__end__"]]]:
     def response_node(state: AgentState) -> Command[Literal["__end__"]]:
-        """Dispatch the agent response to the appropriate channel and end the flow."""
+        """Finalize the agent response and end the flow."""
         messages = state.get("messages", [])
-        channel = cast(object, state.get("channel"))
-        external_id = state.get("external_id")
 
         message_content, _ = _get_last_ai_message(messages)
         if not message_content:
             logger.warning("No AI message found to send")
             return Command(goto=END_NODE, update=state)
 
-        if channel == "cli":
-            _store_conversation_memory(state, messages)
-            return Command(goto=END_NODE, update=state)
-
-        medium = _coerce_medium(channel)
-        if medium is None:
-            logger.error(f"No valid channel found in state: {channel}")
-        elif not external_id:
-            logger.error("No external_id found in state")
-        else:
-            adapter = registry.get(medium)
-            if adapter:
-                adapter.send(external_id, message_content, state)
-            else:
-                logger.error(f"No adapter configured for channel: {medium.value}")
-
         _store_conversation_memory(state, messages)
         return Command(goto=END_NODE, update=state)
 

data/alembic/env.py

@@ -7,12 +7,12 @@
 
 from data.models import Base
 
-load_dotenv()
+_ = load_dotenv()
 
 config = context.config
 
 if config.config_file_name is not None:
-    fileConfig(config.config_file_name)
+    fileConfig(config.config_file_name, disable_existing_loggers=False)
 
 # Override sqlalchemy.url from environment
 _raw_url = os.environ.get("DATABASE_URL", "")

docker-compose.yml

@@ -36,7 +36,8 @@ services:
     container_name: gordie-server
     env_file: .env
     environment:
-      DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/fantasy_agent}
+      DATABASE_URL: postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@postgres:5432/${POSTGRES_DB:-fantasy_agent}
+      GORDIE_LOG_FILE: stderr
       SERVER_HOST: 0.0.0.0
       SERVER_PORT: 8000
     depends_on:

docs/message-flow.md

@@ -4,13 +4,14 @@ How user messages reach Gordie and how Gordie responds, from webhook to delivery
 
 ## Entry Points
 
-Three webhooks accept inbound messages. Each returns immediately and processes the message in a background thread.
+Three webhooks accept inbound messages. Each returns immediately and processes the message in a background thread. Discord can also run through an outbound Gateway bot for local installs.
 
 | Channel | Endpoint | Provider | Route File |
 |---------|----------|----------|------------|
 | Email | `POST /email/webhook` | Mailgun | `server/routes/email_routes.py` |
 | SMS | `POST /sms/webhook` | Sinch | `server/routes/sms_routes.py` |
-| Discord | `POST /discord/interactions` | Discord interactions | `server/routes/discord_routes.py` |
+| Discord interactions | `POST /discord/interactions` | Discord interactions | `server/routes/discord_routes.py` |
+| Discord gateway | Outbound websocket | Discord Gateway | `server/discord_gateway.py` |
 
 ## Webhook Validation
 
@@ -22,7 +23,8 @@ Inbound webhooks run the same guard sequence before processing. Verification log
 4. **SMS-only: rate limiting** — in-memory sliding window (5 messages per 60 seconds per phone number)
 5. **SMS-only: opt-out/opt-in** — STOP/START keywords (and variants like UNSUBSCRIBE, CANCEL, END, QUIT) are handled inline and short-circuit before reaching the agent. Opted-out users receive no responses until they send START
 6. **SMS-only: cold start** — if the phone number has no registered user, a pending user record is created and an OAuth link is sent via SMS instead of invoking the agent
-7. **Discord-only: deferred response** — slash commands return Discord response type `5`, then Gordie edits the original interaction response after the agent finishes
+7. **Discord interactions-only: deferred response** — slash commands return Discord response type `5`, then Gordie edits the original interaction response after the agent finishes
+8. **Discord gateway-only: allowlist + mention filter** — direct messages are accepted from `DISCORD_ALLOWED_USER_IDS`; server messages require an @mention unless `DISCORD_REQUIRE_MENTION=false`
 
 ## Billing Enforcement
 
@@ -40,7 +42,7 @@ Each channel resolves a `thread_id` to maintain conversation continuity through
 
 **SMS** maps each phone number to one `conversation_threads` row for the SMS medium.
 
-**Discord** maps each Discord user ID to one `conversation_threads` row for the Discord medium. The latest Discord interaction token for that thread is stored in `discord_interaction_targets` so the response adapter can edit the deferred original response.
+**Discord** maps each Discord user ID to one `conversation_threads` row for the Discord medium. Interactions mode stores the latest Discord interaction token for that thread in `discord_interaction_targets` so the response adapter can edit the deferred original response. Gateway mode sends the captured response directly back to the Discord channel.
 
 ## Agent Processing
 
@@ -131,12 +133,18 @@ The response node (`agent/response_node.py`) dispatches the final message throug
 1. Strips markdown from the response
 2. Sends as a single SMS via Sinch
 
-**Discord dispatch** (`server/adapters/discord_adapter.py`):
+**Discord interactions dispatch** (`server/adapters/discord_adapter.py`):
 
 1. Looks up the latest `discord_interaction_targets` row for the thread
 2. Truncates content to Discord's 2000-character response limit
 3. Edits the original deferred Discord interaction response
 
+**Discord gateway dispatch** (`server/discord_gateway.py`):
+
+1. Receives messages from Discord over the bot websocket
+2. Runs the same Discord message processor with adapter dispatch disabled
+3. Sends the returned response directly to the originating Discord channel
+
 **Conversation memory** (`agent/memory_store.py`):
 
 After dispatch, the response node calls `summarize_and_store_conversation()` which uses GPT-4o-mini to extract a summary, key topics, players mentioned, and decisions made from the last 10 messages. Summaries are stored in both:
@@ -147,14 +155,15 @@ After dispatch, the response node calls `summarize_and_store_conversation()` whi
 ## Sequence Overview
 
 ```
-User sends SMS/Email/Discord command
+User sends SMS/Email/Discord message
         │
         ▼
   Webhook handler
   (verify signature, deduplicate, timestamp check)
         │
         ├── SMS-only: rate limit, opt-out, cold-start checks
-        ├── Discord-only: defer response + store interaction target
+        ├── Discord interactions: defer response + store interaction target
+        ├── Discord gateway: allowlist + mention filter
         │
         ├── Billing tier enforcement
         │

docs/setup/configuration.md

@@ -32,7 +32,7 @@ See per-service setup docs:
 - `yahoo-oauth.md` — `YAHOO_CLIENT_ID`, `YAHOO_CLIENT_SECRET`
 - `email-mailgun.md` — `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, `MAILGUN_FROM_EMAIL`, `MAILGUN_WEBHOOK_SIGNING_KEY`
 - `sms-sinch.md` — `SINCH_SERVICE_PLAN_ID`, `SINCH_API_TOKEN`, `SINCH_FROM_NUMBER`, `SINCH_WEBHOOK_TOKEN`
-- `discord.md` — `DISCORD_PUBLIC_KEY`, `DISCORD_APPLICATION_ID`
+- `discord.md` — `DISCORD_MODE`, `DISCORD_APPLICATION_ID`, `DISCORD_PUBLIC_KEY`, `DISCORD_BOT_TOKEN`
 
 ## Billing (Creem)
 

docs/setup/database.md

@@ -5,10 +5,11 @@ Gordie uses Postgres for application state (users, OAuth tokens, subscriptions,
 ## Local Postgres via Docker
 
 ```bash
-docker compose up -d postgres
-docker compose exec server uv run alembic upgrade head
+docker compose up -d
 ```
 
+The server applies Alembic migrations automatically before it starts accepting requests.
+
 `docker-compose.yml` defaults to:
 - DB name: `fantasy_agent`
 - User: `postgres`
@@ -34,8 +35,7 @@ LangGraph's PostgresSaver auto-creates its own tables on first import of `agent.
 
 ```bash
 docker compose down -v       # drops the postgres volume
-docker compose up -d postgres
-docker compose exec server uv run alembic upgrade head
+docker compose up -d
 ```
 
 There's a helper script: `scripts/reset_databases.sh` (assumes `gordie-postgres` container).