requirements docs

.env.example

@@ -1,24 +0,0 @@
-# Application Settings
-APP_NAME=Sanctum Chronicler
-APP_ENV=development
-DEBUG=false
-
-# Database
-DATABASE_URL=postgresql+asyncpg://sanctum:password@localhost:5432/sanctum
-DB_PASSWORD=password
-
-# Twitch Configuration
-TWITCH_CLIENT_ID=
-TWITCH_CLIENT_SECRET=
-TWITCH_BOT_USERNAME=
-TWITCH_CHANNEL_NAME=
-
-# LLM Configuration
-# Supported providers: openai, ollama, lm_studio (or leave empty for mock)
-LLM_PROVIDER=
-LLM_BASE_URL=
-LLM_API_KEY=
-LLM_MODEL=gpt-3.5-turbo
-
-# Export Configuration
-EXPORT_PATH=./exports

.gitignore

@@ -44,7 +44,7 @@ pgdata/
 # =========================================
 # Runtime / Exports
 # =========================================
-exports/
+/exports/
 data/
 logs/
 

Dockerfile

@@ -42,7 +42,7 @@ EXPOSE 8000
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-    CMD python -c "import httpx; httpx.get('http://localhost:8000/health')"
+    CMD python -c "import httpx; httpx.get('http://localhost:8000/health').raise_for_status()"
 
 # Run application
 CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

app/agent/modes/hearthkeeper.py

@@ -34,9 +34,18 @@ class HearthkeeperMode:
         """Determine if Hearthkeeper should generate a prompt."""
         return minutes_since_activity >= self.activity_threshold
 
-    async def generate_prompt(self, theme: str | None = None) -> str:
+    async def generate_prompt(
+        self,
+        theme: str | None = None,
+        dashboard: dict | None = None,
+        recent_discussion: list[str] | None = None,
+    ) -> str:
         """Generate a gentle prompt for the stream."""
-        prompt = PromptTemplates.gentle_prompt(theme)
+        prompt = PromptTemplates.gentle_prompt(
+            current_theme=theme,
+            dashboard=dashboard,
+            recent_discussion=recent_discussion or [],
+        )
         response = await self.llm_client.generate(prompt)
         logger.info("Hearthkeeper generated gentle prompt")
         return response

app/agent/orchestrator.py

@@ -1,9 +1,7 @@
 """Agent Orchestrator - Routes messages and manages agent modes."""
 
 import logging
-import uuid
-from datetime import datetime
-from sqlalchemy.ext.asyncio import AsyncSession
+from datetime import datetime, timedelta
 
 from app.agent.policies import (
     ChatActivityPolicy,
@@ -15,10 +13,12 @@ from app.agent.modes.steward import StewardMode
 from app.agent.modes.warden import WardenMode
 from app.agent.modes.librarian import LibrarianMode
 from app.agent.modes.scribe import ScribeMode
+from app.config import settings
 from app.llm.client import LLMClient
-from app.memory.database import async_session_factory
+from app.memory.database import get_session
 from app.memory.models import AgentActionType
 from app.memory.repository import Repository
+from app.twitch.chat import send_chat_message
 
 logger = logging.getLogger(__name__)
 
@@ -32,9 +32,13 @@ class AgentOrchestrator:
     and how to flag suspicious content.
     """
 
-    def __init__(self):
+    def __init__(self, loop_interval_seconds: float = 60.0):
         """Initialize the orchestrator and all modes."""
         self.llm_client = LLMClient()
+        self.loop_interval_seconds = loop_interval_seconds
+        self.hearthkeeper_prompt_interval = timedelta(
+            minutes=settings.HEARTHKEEPER_PROMPT_INTERVAL_MINUTES
+        )
         
         # Initialize modes
         self.hearthkeeper = HearthkeeperMode(self.llm_client)
@@ -63,22 +67,60 @@ class AgentOrchestrator:
         Returns:
             Session ID
         """
-        session_id = str(uuid.uuid4())
-        
-        async with async_session_factory() as db_session:
+        session_id: str | None = None
+        async for db_session in get_session():
             repo = Repository(db_session)
-            await repo.create_session(channel_name)
+            session_id = await repo.create_session(channel_name)
+
+        if session_id is None:
+            raise RuntimeError("Failed to create stream session")
         
         self.active_sessions[session_id] = {
             "channel_name": channel_name,
             "started_at": datetime.utcnow(),
             "message_count": 0,
             "theme": None,
+            "dashboard": None,
+            "last_hearthkeeper_prompt_at": None,
         }
+        self.chat_activity.record_activity(session_id)
         
         logger.info(f"Started session {session_id} for {channel_name}")
         return session_id
 
+    async def restore_active_sessions(self) -> int:
+        """Restore active sessions from the database after app startup."""
+        restored_count = 0
+
+        async for db_session in get_session():
+            repo = Repository(db_session)
+            sessions = await repo.get_active_sessions()
+
+            for session in sessions:
+                recent_messages = await repo.get_recent_human_messages(
+                    session.id,
+                    limit=1,
+                )
+                message_count = await repo.count_messages(session.id)
+                dashboard = await repo.get_dashboard(session.id)
+                last_activity_at = (
+                    recent_messages[0].timestamp if recent_messages else session.started_at
+                )
+
+                self.active_sessions[session.id] = {
+                    "channel_name": session.channel_name,
+                    "started_at": session.started_at,
+                    "message_count": message_count,
+                    "theme": session.theme,
+                    "dashboard": Repository.serialize_dashboard(dashboard),
+                    "last_hearthkeeper_prompt_at": None,
+                }
+                self.chat_activity.record_activity(session.id, occurred_at=last_activity_at)
+                restored_count += 1
+
+        logger.info(f"Restored {restored_count} active sessions")
+        return restored_count
+
     async def end_session(self, session_id: str) -> None:
         """
         End a stream session and trigger ledger generation.
@@ -90,7 +132,7 @@ class AgentOrchestrator:
             logger.warning(f"Session {session_id} not found")
             return
         
-        async with async_session_factory() as db_session:
+        async for db_session in get_session():
             repo = Repository(db_session)
             await repo.end_session(session_id)
         
@@ -122,7 +164,7 @@ class AgentOrchestrator:
         actions = []
         agent_response = None
 
-        async with async_session_factory() as db_session:
+        async for db_session in get_session():
             repo = Repository(db_session)
             
             # Store the message
@@ -136,12 +178,13 @@ class AgentOrchestrator:
         # Record activity
         self.chat_activity.record_activity(session_id)
         session_info["message_count"] += 1
+        session_info["last_hearthkeeper_prompt_at"] = None
 
         # 1. Warden always analyzes (passive mode)
         warden_result = await self.warden.analyze_message(message)
         if warden_result["is_suspicious"]:
             actions.append(f"WARDEN_FLAG: {warden_result['severity']}")
-            async with async_session_factory() as db_session:
+            async for db_session in get_session():
                 repo = Repository(db_session)
                 await repo.record_action(
                     session_id=session_id,
@@ -153,9 +196,12 @@ class AgentOrchestrator:
 
         # 2. Check if we should suppress responses due to active chat
         recent_messages = []
-        async with async_session_factory() as db_session:
+        async for db_session in get_session():
             repo = Repository(db_session)
-            recent_messages = await repo.get_recent_messages(session_id, limit=10)
+            recent_messages = await repo.get_human_messages_since(
+                session_id=session_id,
+                since=datetime.utcnow() - timedelta(minutes=1),
+            )
 
         if self.response_suppression.should_suppress_response(len(recent_messages)):
             logger.debug("Response suppressed due to active chat")
@@ -164,25 +210,7 @@ class AgentOrchestrator:
                 "actions_taken": actions,
             }
 
-        # 3. Hearthkeeper: Generate prompt if chat inactive
-        if self.chat_activity.should_hearthkeeper_prompt(session_id):
-            try:
-                agent_response = await self.hearthkeeper.generate_prompt(
-                    theme=session_info.get("theme")
-                )
-                actions.append("HEARTHKEEPER_PROMPT")
-                async with async_session_factory() as db_session:
-                    repo = Repository(db_session)
-                    await repo.record_action(
-                        session_id=session_id,
-                        action_type=AgentActionType.RESPONSE,
-                        mode="hearthkeeper",
-                        description=agent_response,
-                    )
-            except Exception as e:
-                logger.error(f"Error in Hearthkeeper: {e}")
-
-        # 4. Librarian: Archive important messages (passive)
+        # 3. Librarian: Archive important messages (passive)
         if len(message) > 50:  # Archive longer messages
             await self.librarian.archive_message(message_id, message, username)
 
@@ -195,6 +223,216 @@ class AgentOrchestrator:
             "actions_taken": actions,
         }
 
+    async def emit_agent_response(
+        self,
+        session_id: str,
+        message: str,
+        mode: str,
+        triggered_by_message_id: str | None = None,
+    ) -> dict:
+        """Send an agent response through the outbound chat boundary."""
+        session_info = self.active_sessions.get(session_id)
+        if not session_info:
+            logger.warning(f"Session {session_id} not found")
+            return {"sent": False, "reason": "session_not_found"}
+
+        channel_name = session_info["channel_name"]
+        sent = await send_chat_message(channel_name=channel_name, message=message)
+        bot_username = settings.TWITCH_BOT_USERNAME or "sanctum_chronicler"
+
+        async for db_session in get_session():
+            repo = Repository(db_session)
+            bot_message_id = await repo.add_chat_message(
+                session_id=session_id,
+                username=bot_username,
+                content=message,
+                is_bot=True,
+            )
+            action_id = await repo.record_action(
+                session_id=session_id,
+                action_type=AgentActionType.RESPONSE,
+                mode=mode,
+                description=message,
+                triggered_by_message_id=triggered_by_message_id,
+            )
+
+        session_info["message_count"] += 1
+        logger.info(
+            f"Agent response emitted. Session: {session_id}, Mode: {mode}, Sent: {sent}"
+        )
+        return {
+            "sent": sent,
+            "channel": channel_name,
+            "message_id": bot_message_id,
+            "action_id": action_id,
+        }
+
+    async def run_hearthkeeper_loop_test(
+        self,
+        session_id: str,
+        inactive_minutes: int = 16,
+    ) -> dict:
+        """Exercise the quiet-chat loop and verify it prompts exactly once."""
+        session_info = self.active_sessions.get(session_id)
+        if not session_info:
+            return {"passed": False, "reason": "session_not_found"}
+
+        simulated_activity_at = datetime.utcnow() - timedelta(minutes=inactive_minutes)
+        self.chat_activity.record_activity(
+            session_id=session_id,
+            occurred_at=simulated_activity_at,
+        )
+        session_info["last_hearthkeeper_prompt_at"] = None
+
+        before_count = await self._count_response_actions(
+            session_id=session_id,
+            mode="hearthkeeper",
+        )
+        first_tick = await self._tick_session(session_id)
+        second_tick = await self._tick_session(session_id)
+        after_count = await self._count_response_actions(
+            session_id=session_id,
+            mode="hearthkeeper",
+        )
+        session_info["last_hearthkeeper_prompt_at"] = (
+            datetime.utcnow() - self.hearthkeeper_prompt_interval
+        )
+        third_tick = await self._tick_session(session_id)
+        final_count = await self._count_response_actions(
+            session_id=session_id,
+            mode="hearthkeeper",
+        )
+        prompts_created = after_count - before_count
+        prompts_created_after_interval = final_count - before_count
+
+        return {
+            "passed": (
+                prompts_created == 1
+                and first_tick is not None
+                and second_tick is None
+                and third_tick is not None
+                and prompts_created_after_interval == 2
+            ),
+            "session_id": session_id,
+            "inactive_minutes": inactive_minutes,
+            "prompts_created": prompts_created,
+            "prompts_created_after_interval": prompts_created_after_interval,
+            "first_tick": first_tick,
+            "second_tick": second_tick,
+            "third_tick_after_interval": third_tick,
+        }
+
+    async def _count_response_actions(self, session_id: str, mode: str) -> int:
+        """Count response actions for a mode in a session."""
+        async for db_session in get_session():
+            repo = Repository(db_session)
+            actions = await repo.get_session_actions(session_id)
+            return sum(
+                1
+                for action in actions
+                if action.action_type == AgentActionType.RESPONSE
+                and action.mode == mode
+            )
+        return 0
+
+    def set_loop_interval(self, interval_seconds: float) -> None:
+        """Update how frequently the background agent loop runs."""
+        if interval_seconds < 1:
+            raise ValueError("Loop interval must be at least 1 second")
+        self.loop_interval_seconds = interval_seconds
+
+    def get_loop_status(self) -> dict:
+        """Get background loop configuration and current session count."""
+        return {
+            "interval_seconds": self.loop_interval_seconds,
+            "hearthkeeper_prompt_interval_minutes": int(
+                self.hearthkeeper_prompt_interval.total_seconds() / 60
+            ),
+            "active_session_count": len(self.active_sessions),
+        }
+
+    async def tick(self) -> list[dict]:
+        """Evaluate active sessions for time-based agent behavior."""
+        results = []
+        for session_id in list(self.active_sessions.keys()):
+            result = await self._tick_session(session_id)
+            if result:
+                results.append(result)
+        return results
+
+    async def _tick_session(self, session_id: str) -> dict | None:
+        """Evaluate a single active session during the background loop."""
+        session_info = self.active_sessions.get(session_id)
+        if not session_info:
+            return None
+
+        active_chat_messages = []
+        recent_discussion_messages = []
+        async for db_session in get_session():
+            repo = Repository(db_session)
+            active_chat_messages = await repo.get_human_messages_since(
+                session_id=session_id,
+                since=datetime.utcnow() - timedelta(minutes=1),
+            )
+            recent_discussion_messages = await repo.get_recent_human_messages(
+                session_id=session_id,
+                limit=5,
+            )
+
+        if self.response_suppression.should_suppress_response(len(active_chat_messages)):
+            return {
+                "session_id": session_id,
+                "actions_taken": [],
+                "agent_response": None,
+                "reason": "active_chat",
+            }
+
+        if not self.chat_activity.should_hearthkeeper_prompt(session_id):
+            return None
+
+        last_activity_at = self.chat_activity.last_activity_at(session_id)
+        last_prompt_at = session_info.get("last_hearthkeeper_prompt_at")
+        if last_activity_at and last_prompt_at and last_activity_at > last_prompt_at:
+            session_info["last_hearthkeeper_prompt_at"] = None
+            last_prompt_at = None
+        if (
+            last_prompt_at
+            and datetime.utcnow() - last_prompt_at < self.hearthkeeper_prompt_interval
+        ):
+            return None
+
+        try:
+            recent_discussion = [
+                message.content for message in recent_discussion_messages[:5]
+            ]
+            agent_response = await self.hearthkeeper.generate_prompt(
+                theme=session_info.get("theme"),
+                dashboard=session_info.get("dashboard"),
+                recent_discussion=recent_discussion,
+            )
+            session_info["last_hearthkeeper_prompt_at"] = datetime.utcnow()
+            delivery = await self.emit_agent_response(
+                session_id=session_id,
+                message=agent_response,
+                mode="hearthkeeper",
+            )
+
+            return {
+                "session_id": session_id,
+                "actions_taken": ["HEARTHKEEPER_PROMPT"],
+                "agent_response": agent_response,
+                "delivery": delivery,
+                "reason": "inactive_chat",
+            }
+        except Exception as e:
+            logger.error(f"Error in Hearthkeeper loop: {e}")
+            return {
+                "session_id": session_id,
+                "actions_taken": [],
+                "agent_response": None,
+                "reason": "hearthkeeper_error",
+            }
+
     async def get_session_status(self, session_id: str) -> dict:
         """Get status of a session."""
         if session_id not in self.active_sessions:
@@ -208,4 +446,5 @@ class AgentOrchestrator:
             "message_count": session["message_count"],
             "uptime_seconds": (datetime.utcnow() - session["started_at"]).total_seconds(),
             "theme": session.get("theme"),
+            "dashboard": session.get("dashboard"),
         }

app/agent/policies.py

@@ -19,9 +19,13 @@ class ChatActivityPolicy:
         self.inactivity_threshold = timedelta(minutes=inactivity_threshold_minutes)
         self.last_message_time: dict[str, datetime] = {}
 
-    def record_activity(self, session_id: str) -> None:
+    def record_activity(self, session_id: str, occurred_at: datetime | None = None) -> None:
         """Record that chat activity occurred."""
-        self.last_message_time[session_id] = datetime.utcnow()
+        self.last_message_time[session_id] = occurred_at or datetime.utcnow()
+
+    def last_activity_at(self, session_id: str) -> datetime | None:
+        """Get the most recent chat activity time for a session."""
+        return self.last_message_time.get(session_id)
 
     def minutes_since_activity(self, session_id: str) -> int:
         """Get minutes since last chat message."""

app/config.py

@@ -1,5 +1,6 @@
 """Configuration management using pydantic-settings."""
 
+from pydantic import field_validator
 from pydantic_settings import BaseSettings
 from typing import Optional
 
@@ -11,6 +12,31 @@ class Settings(BaseSettings):
     APP_NAME: str = "Sanctum Chronicler"
     APP_ENV: str = "development"
     DEBUG: bool = False
+    ADMIN_API_KEY: Optional[str] = None
+
+    @field_validator("DEBUG", mode="before")
+    @classmethod
+    def parse_debug(cls, value: object) -> bool:
+        """Parse permissive runtime DEBUG values from shell environments."""
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            normalized = value.strip().lower()
+            if normalized in {"1", "true", "t", "yes", "y", "on", "debug"}:
+                return True
+            if normalized in {
+                "0",
+                "false",
+                "f",
+                "no",
+                "n",
+                "off",
+                "release",
+                "prod",
+                "production",
+            }:
+                return False
+        return False
 
     # Database
     DATABASE_URL: str = "postgresql+asyncpg://sanctum:password@localhost:5432/sanctum"
@@ -27,6 +53,10 @@ class Settings(BaseSettings):
     LLM_API_KEY: Optional[str] = None
     LLM_MODEL: str = "gpt-3.5-turbo"
 
+    # Agent loop
+    AGENT_LOOP_INTERVAL_SECONDS: float = 60.0
+    HEARTHKEEPER_PROMPT_INTERVAL_MINUTES: int = 15
+
     # Export
     EXPORT_PATH: str = "exports"
 

app/exports/__init__.py

@@ -0,0 +1 @@
+"""Exports module."""

app/exports/markdown.py

@@ -0,0 +1,142 @@
+"""Markdown export functionality for stream ledgers."""
+
+import logging
+from datetime import datetime
+from pathlib import Path
+
+from app.config import settings
+from app.memory.database import get_session
+from app.memory.repository import Repository
+
+logger = logging.getLogger(__name__)
+
+
+class MarkdownExporter:
+    """Exports stream session data as markdown ledgers."""
+
+    def __init__(self, export_path: str | None = None):
+        """
+        Initialize exporter.
+        
+        Args:
+            export_path: Directory to export ledgers to (defaults to settings.EXPORT_PATH)
+        """
+        self.export_path = Path(export_path or settings.EXPORT_PATH)
+        self.export_path.mkdir(parents=True, exist_ok=True)
+
+    async def export_session(self, session_id: str) -> str:
+        """
+        Export a session as a markdown ledger.
+        
+        Args:
+            session_id: Session ID to export
+            
+        Returns:
+            Markdown content
+        """
+        async for db_session in get_session():
+            repo = Repository(db_session)
+            
+            session = await repo.get_session(session_id)
+            if not session:
+                logger.warning(f"Session {session_id} not found")
+                return ""
+            
+            # Gather data
+            messages = await repo.get_recent_messages(session_id, limit=1000)
+            actions = await repo.get_session_actions(session_id)
+            clips = await repo.get_clip_candidates(session_id)
+            seeds = await repo.get_blog_seeds(session_id)
+            dashboard = await repo.get_dashboard(session_id)
+
+        dashboard_data = Repository.serialize_dashboard(dashboard)
+
+        # Build markdown
+        date = session.started_at.strftime("%Y-%m-%d")
+        ledger = f"# Sanctum Ledger — {date}\n\n"
+        ledger += f"**Channel:** {session.channel_name}\n"
+        ledger += f"**Started:** {session.started_at.isoformat()}\n"
+        if session.ended_at:
+            ledger += f"**Ended:** {session.ended_at.isoformat()}\n"
+        ledger += "\n"
+        
+        # Stream Theme
+        ledger += "## Stream Theme\n"
+        if dashboard_data:
+            if dashboard_data.get("stream_title"):
+                ledger += f"**Title:** {dashboard_data['stream_title']}\n"
+            if dashboard_data.get("game"):
+                ledger += f"**Game:** {dashboard_data['game']}\n"
+            if dashboard_data.get("mood"):
+                ledger += f"**Mood:** {dashboard_data['mood']}\n"
+            if dashboard_data.get("content_angle"):
+                ledger += f"**Content Angle:** {dashboard_data['content_angle']}\n"
+            if dashboard_data.get("session_goals"):
+                ledger += "\n**Session Goals**\n"
+                for goal in dashboard_data["session_goals"]:
+                    ledger += f"- {goal}\n"
+        elif session.theme:
+            ledger += f"{session.theme}\n"
+        else:
+            ledger += "*No theme recorded*\n"
+        ledger += "\n"
+        
+        # Notable Discussion
+        ledger += "## Notable Discussion\n"
+        if messages:
+            for msg in messages[:20]:  # Latest 20 messages
+                ledger += f"- **{msg.username}:** {msg.content[:100]}\n"
+        else:
+            ledger += "*No messages recorded*\n"
+        ledger += "\n"
+        
+        # Agent Actions
+        ledger += "## Agent Actions\n"
+        if actions:
+            for action in actions:
+                ledger += f"- **{action.mode}** ({action.action_type}): {action.description}\n"
+        else:
+            ledger += "*No agent actions recorded*\n"
+        ledger += "\n"
+        
+        # Clip Candidates
+        ledger += "## Clip Candidates\n"
+        if clips:
+            for clip in clips:
+                ledger += f"- {clip.reason}\n"
+        else:
+            ledger += "*No clip candidates identified*\n"
+        ledger += "\n"
+        
+        # Blog Seeds
+        ledger += "## Blog Seeds\n"
+        if seeds:
+            for seed in seeds:
+                ledger += f"- **{seed.topic}:** {seed.description}\n"
+        else:
+            ledger += "*No blog seeds proposed*\n"
+        ledger += "\n"
+        
+        logger.info(f"Generated ledger for session {session_id}")
+        return ledger
+
+    async def save_session_ledger(self, session_id: str) -> Path:
+        """
+        Export session and save to file.
+        
+        Args:
+            session_id: Session ID
+            
+        Returns:
+            Path to saved file
+        """
+        ledger = await self.export_session(session_id)
+        
+        date = datetime.utcnow().strftime("%Y-%m-%d")
+        filename = f"ledger_{date}_{session_id[:8]}.md"
+        filepath = self.export_path / filename
+        
+        filepath.write_text(ledger, encoding="utf-8")
+        logger.info(f"Saved ledger to {filepath}")
+        
+        return filepath

app/llm/client.py

@@ -106,6 +106,12 @@ class LLMClient:
         """
         logger.debug(f"Mock generation for prompt: {prompt[:50]}...")
 
+        if "content angle:" in prompt.lower():
+            for line in prompt.splitlines():
+                if line.lower().startswith("content angle:"):
+                    angle = line.split(":", 1)[1].strip()
+                    return f"The quiet here keeps circling back to {angle}."
+        
         # Simple deterministic responses for testing
         if "hello" in prompt.lower():
             return "Greetings, traveler! Welcome to The Sanctum."

app/llm/prompts.py

@@ -7,11 +7,37 @@ class PromptTemplates:
     """Collection of prompt templates for different modes."""
 
     @staticmethod
-    def gentle_prompt(current_theme: Optional[str] = None) -> str:
+    def gentle_prompt(
+        current_theme: Optional[str] = None,
+        dashboard: Optional[dict] = None,
+        recent_discussion: Optional[list[str]] = None,
+    ) -> str:
         """Generate a gentle prompt when chat has been inactive."""
+        dashboard = dashboard or {}
+        recent_discussion = recent_discussion or []
+
+        context_lines = [
+            "Generate one brief Hearthkeeper prompt for a calm, reflective livestream.",
+            "The prompt must be restrained, thematic, and not engagement bait.",
+        ]
+        if dashboard.get("stream_title"):
+            context_lines.append(f"Stream title: {dashboard['stream_title']}")
+        if dashboard.get("game"):
+            context_lines.append(f"Game: {dashboard['game']}")
+        if dashboard.get("mood"):
+            context_lines.append(f"Mood: {dashboard['mood']}")
+        if dashboard.get("content_angle"):
+            context_lines.append(f"Content angle: {dashboard['content_angle']}")
+        if dashboard.get("session_goals"):
+            goals = "; ".join(dashboard["session_goals"])
+            context_lines.append(f"Session goals: {goals}")
         if current_theme:
-            return f"Gently prompt the chat about: {current_theme}"
-        return "Generate a gentle, inviting prompt to encourage discussion in the stream."
+            context_lines.append(f"Current theme: {current_theme}")
+        if recent_discussion:
+            context_lines.append("Recent human discussion:")
+            context_lines.extend(f"- {message}" for message in recent_discussion[:5])
+
+        return "\n".join(context_lines)
 
     @staticmethod
     def steward_response(message: str, context: Optional[str] = None) -> str:

app/main.py

@@ -1,13 +1,18 @@
 """FastAPI main application."""
 
-from fastapi import FastAPI, HTTPException
-from fastapi.responses import JSONResponse
+import asyncio
+import secrets
+from contextlib import suppress
+from pydantic import BaseModel, Field
+from fastapi import Depends, FastAPI, Form, Header, HTTPException
 from datetime import datetime
 import logging
 
 from app.config import settings
 from app.agent.orchestrator import AgentOrchestrator
 from app.memory.database import init_db
+from app.memory.database import get_session as get_db_session
+from app.memory.repository import Repository
 from app.exports.markdown import MarkdownExporter
 
 logger = logging.getLogger(__name__)
@@ -18,17 +23,67 @@ app = FastAPI(
     version="0.1.0",
 )
 
+
+class DashboardRequest(BaseModel):
+    """Request body for saving a stream dashboard."""
+
+    session_id: str
+    raw_markdown: str
+    stream_title: str | None = None
+    game: str | None = None
+    mood: str | None = None
+    go_live_notification: str | None = None
+    social_post: str | None = None
+    session_goals: list[str] = Field(default_factory=list)
+    content_angle: str | None = None
+
 # Global orchestrator instance
 orchestrator: AgentOrchestrator | None = None
+agent_loop_task: asyncio.Task | None = None
+
+
+async def require_admin(
+    admin_token: str | None = Header(default=None, alias="X-Admin-Token"),
+) -> None:
+    """Require the configured admin token for mutable/control endpoints."""
+    if not settings.ADMIN_API_KEY:
+        raise HTTPException(status_code=503, detail="Admin API key is not configured")
+    if not admin_token or not secrets.compare_digest(
+        admin_token,
+        settings.ADMIN_API_KEY,
+    ):
+        raise HTTPException(status_code=401, detail="Invalid admin token")
+
+
+async def agent_loop() -> None:
+    """Run periodic time-based agent behavior for active sessions."""
+    if not orchestrator:
+        return
+
+    while True:
+        try:
+            results = await orchestrator.tick()
+            if results:
+                logger.info(f"Agent loop actions: {results}")
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.error(f"Agent loop tick failed: {e}")
+
+        await asyncio.sleep(orchestrator.loop_interval_seconds)
 
 
 @app.on_event("startup")
 async def startup_event():
     """Initialize database and services on startup."""
-    global orchestrator
+    global orchestrator, agent_loop_task
     try:
         await init_db()
-        orchestrator = AgentOrchestrator()
+        orchestrator = AgentOrchestrator(
+            loop_interval_seconds=settings.AGENT_LOOP_INTERVAL_SECONDS
+        )
+        await orchestrator.restore_active_sessions()
+        agent_loop_task = asyncio.create_task(agent_loop())
         logger.info("Application started successfully")
     except Exception as e:
         logger.error(f"Failed to start application: {e}")
@@ -38,6 +93,10 @@ async def startup_event():
 @app.on_event("shutdown")
 async def shutdown_event():
     """Clean up resources on shutdown."""
+    if agent_loop_task:
+        agent_loop_task.cancel()
+        with suppress(asyncio.CancelledError):
+            await agent_loop_task
     logger.info("Application shutting down")
 
 
@@ -52,8 +111,8 @@ async def health_check() -> dict:
     }
 
 
-@app.post("/admin/session/start")
-async def start_session(channel_name: str) -> dict:
+@app.post("/admin/session/start", dependencies=[Depends(require_admin)])
+async def start_session(channel_name: str = Form(...)) -> dict:
     """Start a new stream session."""
     if not orchestrator:
         raise HTTPException(status_code=503, detail="Orchestrator not initialized")
@@ -67,8 +126,8 @@ async def start_session(channel_name: str) -> dict:
     }
 
 
-@app.post("/admin/session/end")
-async def end_session(session_id: str) -> dict:
+@app.post("/admin/session/end", dependencies=[Depends(require_admin)])
+async def end_session(session_id: str = Form(...)) -> dict:
     """End the current stream session."""
     if not orchestrator:
         raise HTTPException(status_code=503, detail="Orchestrator not initialized")
@@ -81,8 +140,8 @@ async def end_session(session_id: str) -> dict:
     }
 
 
-@app.post("/admin/test-message")
-async def test_message(session_id: str, message: str, username: str = "test_user") -> dict:
+@app.post("/admin/test-message", dependencies=[Depends(require_admin)])
+async def test_message(session_id: str = Form(...), message: str = Form(...), username: str = Form("test_user")) -> dict:
     """Send a test message to the orchestrator."""
     if not orchestrator:
         raise HTTPException(status_code=503, detail="Orchestrator not initialized")
@@ -100,7 +159,111 @@ async def test_message(session_id: str, message: str, username: str = "test_user
     }
 
 
-@app.get("/admin/ledger")
+@app.post("/admin/test-agent-response", dependencies=[Depends(require_admin)])
+async def test_agent_response(
+    session_id: str = Form(...),
+    message: str = Form(...),
+    mode: str = Form("admin"),
+) -> dict:
+    """Send a test agent response through the outbound boundary."""
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Orchestrator not initialized")
+
+    delivery = await orchestrator.emit_agent_response(
+        session_id=session_id,
+        message=message,
+        mode=mode,
+    )
+    if not delivery.get("sent"):
+        raise HTTPException(status_code=404, detail=delivery.get("reason", "send_failed"))
+
+    return {
+        "status": "agent_response_emitted",
+        "delivery": delivery,
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+@app.post("/admin/test-loop-inactivity", dependencies=[Depends(require_admin)])
+async def test_loop_inactivity(
+    session_id: str = Form(...),
+    inactive_minutes: int = Form(16),
+) -> dict:
+    """Verify the quiet-chat loop records exactly one Hearthkeeper prompt."""
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Orchestrator not initialized")
+
+    result = await orchestrator.run_hearthkeeper_loop_test(
+        session_id=session_id,
+        inactive_minutes=inactive_minutes,
+    )
+    if result.get("reason") == "session_not_found":
+        raise HTTPException(status_code=404, detail="Active session not found")
+
+    return {
+        "status": "passed" if result["passed"] else "failed",
+        "result": result,
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+def serialize_dashboard(dashboard) -> dict:
+    """Serialize a dashboard database model into an API response."""
+    return Repository.serialize_dashboard(dashboard)
+
+
+@app.post("/admin/session/dashboard", dependencies=[Depends(require_admin)])
+async def save_session_dashboard(request: DashboardRequest) -> dict:
+    """Create or update the approved dashboard for a stream session."""
+    async for db_session in get_db_session():
+        repo = Repository(db_session)
+        stream_session = await repo.get_session(request.session_id)
+        if not stream_session:
+            raise HTTPException(status_code=404, detail="Session not found")
+
+        dashboard = await repo.upsert_dashboard(
+            session_id=request.session_id,
+            raw_markdown=request.raw_markdown,
+            stream_title=request.stream_title,
+            game=request.game,
+            mood=request.mood,
+            go_live_notification=request.go_live_notification,
+            social_post=request.social_post,
+            session_goals=request.session_goals,
+            content_angle=request.content_angle,
+        )
+
+    if orchestrator and request.session_id in orchestrator.active_sessions:
+        orchestrator.active_sessions[request.session_id]["dashboard"] = (
+            serialize_dashboard(dashboard)
+        )
+        orchestrator.active_sessions[request.session_id]["theme"] = (
+            request.content_angle or request.stream_title
+        )
+
+    return {
+        "status": "dashboard_saved",
+        "dashboard": serialize_dashboard(dashboard),
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+@app.get("/admin/session/dashboard", dependencies=[Depends(require_admin)])
+async def get_session_dashboard(session_id: str) -> dict:
+    """Get the approved dashboard for a stream session."""
+    async for db_session in get_db_session():
+        repo = Repository(db_session)
+        dashboard = await repo.get_dashboard(session_id)
+        if not dashboard:
+            raise HTTPException(status_code=404, detail="Dashboard not found")
+
+    return {
+        "dashboard": serialize_dashboard(dashboard),
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+@app.get("/admin/ledger", dependencies=[Depends(require_admin)])
 async def get_ledger(session_id: str) -> dict:
     """Get the markdown ledger for a session."""
     if not orchestrator:
@@ -116,6 +279,53 @@ async def get_ledger(session_id: str) -> dict:
     }
 
 
+@app.get("/admin/session/status", dependencies=[Depends(require_admin)])
+async def get_session_status(session_id: str) -> dict:
+    """Get status for an active stream session."""
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Orchestrator not initialized")
+
+    status = await orchestrator.get_session_status(session_id)
+    if not status:
+        raise HTTPException(status_code=404, detail="Active session not found")
+
+    return {
+        **status,
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+@app.get("/admin/loop/status", dependencies=[Depends(require_admin)])
+async def get_loop_status() -> dict:
+    """Get the background agent loop runtime configuration."""
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Orchestrator not initialized")
+
+    return {
+        "status": "running" if agent_loop_task and not agent_loop_task.done() else "stopped",
+        **orchestrator.get_loop_status(),
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+@app.post("/admin/loop/frequency", dependencies=[Depends(require_admin)])
+async def set_loop_frequency(interval_seconds: float = Form(...)) -> dict:
+    """Set how frequently the background agent loop runs."""
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Orchestrator not initialized")
+
+    try:
+        orchestrator.set_loop_interval(interval_seconds)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    return {
+        "status": "loop_frequency_updated",
+        "interval_seconds": orchestrator.loop_interval_seconds,
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run(

app/memory/models.py

@@ -35,6 +35,24 @@ class ChatMessage(Base):
     is_moderator = Column(Boolean, default=False)
 
 
+class StreamDashboard(Base):
+    """Stores the approved stream dashboard for a session."""
+
+    __tablename__ = "stream_dashboards"
+
+    session_id = Column(String, primary_key=True)
+    raw_markdown = Column(Text, nullable=False)
+    stream_title = Column(String, nullable=True)
+    game = Column(String, nullable=True)
+    mood = Column(String, nullable=True)
+    go_live_notification = Column(Text, nullable=True)
+    social_post = Column(Text, nullable=True)
+    session_goals = Column(Text, nullable=True)  # JSON array of strings
+    content_angle = Column(Text, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+
+
 class AgentActionType(str, Enum):
     """Types of actions the agent can take."""
 

app/memory/repository.py

@@ -1,13 +1,15 @@
 """Data access layer for database operations."""
 
+import json
 import logging
 import uuid
 from datetime import datetime
-from sqlalchemy import select, update
+from sqlalchemy import func, select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.memory.models import (
     StreamSession,
+    StreamDashboard,
     ChatMessage,
     AgentAction,
     ClipCandidate,
@@ -56,6 +58,98 @@ class Repository:
         result = await self.session.execute(stmt)
         return result.scalars().first()
 
+    async def get_active_sessions(self) -> list[StreamSession]:
+        """Retrieve sessions that are still marked active."""
+        stmt = (
+            select(StreamSession)
+            .where(StreamSession.is_active.is_(True))
+            .order_by(StreamSession.started_at.asc())
+        )
+        result = await self.session.execute(stmt)
+        return list(result.scalars().all())
+
+    # Stream Dashboard operations
+
+    async def upsert_dashboard(
+        self,
+        session_id: str,
+        raw_markdown: str,
+        stream_title: str | None = None,
+        game: str | None = None,
+        mood: str | None = None,
+        go_live_notification: str | None = None,
+        social_post: str | None = None,
+        session_goals: list[str] | None = None,
+        content_angle: str | None = None,
+    ) -> StreamDashboard:
+        """Create or update a stream dashboard for a session."""
+        dashboard = await self.get_dashboard(session_id)
+        now = datetime.utcnow()
+        goals_json = json.dumps(session_goals or [])
+
+        if dashboard is None:
+            dashboard = StreamDashboard(
+                session_id=session_id,
+                raw_markdown=raw_markdown,
+                stream_title=stream_title,
+                game=game,
+                mood=mood,
+                go_live_notification=go_live_notification,
+                social_post=social_post,
+                session_goals=goals_json,
+                content_angle=content_angle,
+                created_at=now,
+                updated_at=now,
+            )
+            self.session.add(dashboard)
+        else:
+            dashboard.raw_markdown = raw_markdown
+            dashboard.stream_title = stream_title
+            dashboard.game = game
+            dashboard.mood = mood
+            dashboard.go_live_notification = go_live_notification
+            dashboard.social_post = social_post
+            dashboard.session_goals = goals_json
+            dashboard.content_angle = content_angle
+            dashboard.updated_at = now
+
+        await self.session.commit()
+        logger.info(f"Saved dashboard for session {session_id}")
+        return dashboard
+
+    async def get_dashboard(self, session_id: str) -> StreamDashboard | None:
+        """Retrieve the dashboard for a session."""
+        stmt = select(StreamDashboard).where(StreamDashboard.session_id == session_id)
+        result = await self.session.execute(stmt)
+        return result.scalars().first()
+
+    @staticmethod
+    def serialize_dashboard(dashboard: StreamDashboard | None) -> dict | None:
+        """Serialize a dashboard model into a plain dict."""
+        if dashboard is None:
+            return None
+
+        session_goals = []
+        if dashboard.session_goals:
+            try:
+                session_goals = json.loads(dashboard.session_goals)
+            except json.JSONDecodeError:
+                session_goals = []
+
+        return {
+            "session_id": dashboard.session_id,
+            "raw_markdown": dashboard.raw_markdown,
+            "stream_title": dashboard.stream_title,
+            "game": dashboard.game,
+            "mood": dashboard.mood,
+            "go_live_notification": dashboard.go_live_notification,
+            "social_post": dashboard.social_post,
+            "session_goals": session_goals,
+            "content_angle": dashboard.content_angle,
+            "created_at": dashboard.created_at.isoformat(),
+            "updated_at": dashboard.updated_at.isoformat(),
+        }
+
     # Chat Message operations
 
     async def add_chat_message(
@@ -95,6 +189,61 @@ class Repository:
         result = await self.session.execute(stmt)
         return list(result.scalars().all())
 
+    async def get_recent_human_messages(
+        self, session_id: str, limit: int = 50
+    ) -> list[ChatMessage]:
+        """Get recent non-bot chat messages from a session."""
+        stmt = (
+            select(ChatMessage)
+            .where(
+                ChatMessage.session_id == session_id,
+                ChatMessage.is_bot.is_(False),
+            )
+            .order_by(ChatMessage.timestamp.desc())
+            .limit(limit)
+        )
+        result = await self.session.execute(stmt)
+        return list(result.scalars().all())
+
+    async def count_messages(self, session_id: str) -> int:
+        """Count chat messages stored for a session."""
+        stmt = select(func.count()).select_from(ChatMessage).where(
+            ChatMessage.session_id == session_id
+        )
+        result = await self.session.execute(stmt)
+        return result.scalar_one()
+
+    async def get_messages_since(
+        self, session_id: str, since: datetime
+    ) -> list[ChatMessage]:
+        """Get messages recorded since a specific timestamp."""
+        stmt = (
+            select(ChatMessage)
+            .where(
+                ChatMessage.session_id == session_id,
+                ChatMessage.timestamp >= since,
+            )
+            .order_by(ChatMessage.timestamp.desc())
+        )
+        result = await self.session.execute(stmt)
+        return list(result.scalars().all())
+
+    async def get_human_messages_since(
+        self, session_id: str, since: datetime
+    ) -> list[ChatMessage]:
+        """Get non-bot messages recorded since a specific timestamp."""
+        stmt = (
+            select(ChatMessage)
+            .where(
+                ChatMessage.session_id == session_id,
+                ChatMessage.is_bot.is_(False),
+                ChatMessage.timestamp >= since,
+            )
+            .order_by(ChatMessage.timestamp.desc())
+        )
+        result = await self.session.execute(stmt)
+        return list(result.scalars().all())
+
     # Agent Action operations
 
     async def record_action(

dashboard-prompt.md

@@ -0,0 +1,56 @@
+# Role
+
+You are a thoughtful RPG analyst, calm and introspective streamer, and content strategist for the _Withered Sanctum_ brand.
+# Context
+
+- Today’s Game: [INSERT GAME]
+- Current Mood/Energy Level: [Low / Medium / High / Reflective / etc.]
+- Familiarity with Game: [New / Some Experience / Very Familiar]
+- Recent Experience (optional): [e.g., “Struggled to get into it”, “Had a great session last time”]
+- Stream Start Time: [INSERT TIME]
+# Output Requirements
+
+Create a **Stream Dashboard** with the following sections:
+### 1. Stream Title
+
+- Should feel grounded, thoughtful, and slightly literary
+- Avoid hype-heavy or clickbait tone
+- Reflect the _experience_ or _journey_, not just the game
+
+### 2. Twitch Go Live Notification
+
+- Short (1–2 sentences)
+- Calm, inviting tone
+- Should feel like an invitation, not an advertisement
+
+### 3. Twitter (X) Announcement Post
+
+- Written 10 minutes before going live
+- Slightly more outward-facing, but still restrained and authentic
+- Optional light hook, but no hype language
+- Include 2–4 relevant hashtags
+
+### 4. Session Goals
+
+- 3–5 simple, achievable goals
+- Can include:
+    - Progress goals (quests, systems, areas)
+    - Comfort goals (learn mechanics, reduce friction)
+    - Personal goals (stay present, avoid rushing)
+
+### 5. One Content Angle
+
+- A single lens or theme for the stream
+- Should elevate the stream beyond “just gameplay”
+- Examples:
+    - First impressions vs. long-term potential
+    - Systems friction vs. player reward
+    - Narrative tone and immersion
+    - “Why this game hasn’t hooked me (yet)”
+- Keep it subtle, not forced—something to return to during quiet moments
+
+### Tone Guidance
+
+- Calm, reflective, slightly philosophical
+- Low-energy friendly (never forced enthusiasm)
+- Feels like a seasoned player sharing perspective, not performing

docker-compose.yml

@@ -32,6 +32,7 @@ services:
       APP_NAME: "Sanctum Chronicler"
       APP_ENV: ${APP_ENV:-development}
       DEBUG: ${DEBUG:-false}
+      ADMIN_API_KEY: ${ADMIN_API_KEY:-}
       DATABASE_URL: postgresql+asyncpg://sanctum:${DB_PASSWORD:-password}@sanctum-db:5432/sanctum
       TWITCH_CLIENT_ID: ${TWITCH_CLIENT_ID:-}
       TWITCH_CLIENT_SECRET: ${TWITCH_CLIENT_SECRET:-}
@@ -41,15 +42,17 @@ services:
       LLM_BASE_URL: ${LLM_BASE_URL:-}
       LLM_API_KEY: ${LLM_API_KEY:-}
       LLM_MODEL: ${LLM_MODEL:-gpt-3.5-turbo}
+      AGENT_LOOP_INTERVAL_SECONDS: ${AGENT_LOOP_INTERVAL_SECONDS:-60}
+      HEARTHKEEPER_PROMPT_INTERVAL_MINUTES: ${HEARTHKEEPER_PROMPT_INTERVAL_MINUTES:-15}
       EXPORT_PATH: /app/exports
     volumes:
       - ./exports:/app/exports
-    ports:
-      - "8000:8000"
     networks:
-      - sanctum-net
+      sanctum-net: {}
+      sanctum-lan:
+        ipv4_address: 192.168.5.92
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      test: ["CMD", "python", "-c", "import httpx; httpx.get('http://localhost:8000/health').raise_for_status()"]
       interval: 30s
       timeout: 3s
       retries: 3
@@ -62,3 +65,6 @@ volumes:
 networks:
   sanctum-net:
     driver: bridge
+  sanctum-lan:
+    external: true
+    name: blog_network

prompt.md

@@ -0,0 +1,173 @@
+Build a Dockerized Python MVP called sanctum-agent.
+
+Goal:
+Create scaffolding for an AI stream assistant called “The Sanctum Chronicler.” It should eventually connect to Twitch chat, monitor stream discussion, lightly guide conversation, store stream events, and export a post-stream markdown ledger.
+
+Tech stack:
+- Python 3.12
+- FastAPI
+- PostgreSQL
+- Docker Compose
+- Async architecture
+- Markdown export
+- Environment variables via .env
+- Placeholder LLM client that can later support OpenAI, Ollama, or LM Studio
+
+Project structure:
+
+sanctum-agent/
+  app/
+    main.py
+    config.py
+
+    twitch/
+      __init__.py
+      eventsub.py
+      chat.py
+
+    agent/
+      __init__.py
+      orchestrator.py
+      policies.py
+      modes/
+        __init__.py
+        hearthkeeper.py
+        steward.py
+        warden.py
+        librarian.py
+        scribe.py
+
+    memory/
+      __init__.py
+      database.py
+      models.py
+      repository.py
+
+    llm/
+      __init__.py
+      client.py
+      prompts.py
+
+    exports/
+      __init__.py
+      markdown.py
+
+  exports/
+  data/
+  Dockerfile
+  docker-compose.yml
+  requirements.txt
+  .env.example
+  README.md
+
+Requirements:
+
+1. FastAPI app
+Create endpoints:
+- GET /health
+- POST /admin/session/start
+- POST /admin/session/end
+- GET /admin/ledger
+- POST /admin/test-message
+
+2. Configuration
+Create app/config.py using pydantic-settings.
+Support these environment variables:
+- APP_NAME
+- APP_ENV
+- DATABASE_URL
+- TWITCH_CLIENT_ID
+- TWITCH_CLIENT_SECRET
+- TWITCH_BOT_USERNAME
+- TWITCH_CHANNEL_NAME
+- LLM_PROVIDER
+- LLM_BASE_URL
+- LLM_API_KEY
+- EXPORT_PATH
+
+3. Database
+Use SQLAlchemy async if reasonable.
+Create models for:
+- StreamSession
+- ChatMessage
+- AgentAction
+- ClipCandidate
+- BlogSeed
+
+The database layer can be functional scaffolding. It does not need full production migrations yet.
+
+4. Agent Orchestrator
+Create an AgentOrchestrator class that:
+- receives chat messages
+- stores them
+- decides whether the agent should respond
+- suppresses responses when human chat is active
+- routes behavior to internal modes
+
+Add a simple policy:
+- If no human chat for 15 minutes, Hearthkeeper may generate a gentle prompt.
+- If chat is active, agent stays silent.
+- If message contains suspicious Discord-growth language, Warden flags it.
+
+5. Modes
+Create placeholder classes:
+- HearthkeeperMode
+- StewardMode
+- WardenMode
+- LibrarianMode
+- ScribeMode
+
+Each should have clear docstrings explaining its purpose.
+
+6. LLM Client
+Create an LLMClient abstraction with a generate() method.
+For now, return deterministic placeholder text if no provider is configured.
+
+7. Markdown Export
+Create a markdown exporter that generates:
+
+# Sanctum Ledger — YYYY-MM-DD
+
+## Stream Theme
+
+## Notable Discussion
+
+## Agent Actions
+
+## Clip Candidates
+
+## Blog Seeds
+
+8. Twitch Layer
+Create placeholder Twitch modules:
+- eventsub.py should define a TwitchEventSubClient class with connect(), disconnect(), and listen() stubs.
+- chat.py should define send_chat_message() as a placeholder.
+Do not implement real OAuth yet. Add TODO comments with where EventSub and Send Chat Message API integration will go.
+
+9. Docker
+Create:
+- Dockerfile for FastAPI app
+- docker-compose.yml with:
+  - sanctum-agent
+  - sanctum-db using postgres:16
+
+10. README
+Write a README with:
+- project purpose
+- architecture overview
+- setup steps
+- docker compose commands
+- current limitations
+- next implementation steps
+
+Style:
+- Keep code clean and readable.
+- Use type hints.
+- Add comments where future Twitch, Discord, and LLM integrations will be inserted.
+- Do not overbuild.
+- This is scaffolding, not a finished production bot.
+
+After generating the files, also provide:
+1. a file tree
+2. commands to run the app
+3. a short explanation of the next practical implementation step

requirements.txt

@@ -7,3 +7,4 @@ asyncpg==0.29.0
 psycopg2-binary==2.9.9
 httpx==0.25.2
 python-dotenv==1.0.0
+python-multipart==0.0.6

usecases.md

@@ -0,0 +1,337 @@
+# Sanctum Chronicler Use Cases
+
+## Project
+Withered Sanctum — Sanctum Chronicler
+
+---
+
+# Purpose
+
+Hearthkeeper Mode exists to preserve conversational continuity and reflective atmosphere during live streams.
+
+The goal of Hearthkeeper is **not** to simulate viewers, inflate engagement, or dominate discussion.
+
+Its purpose is to:
+
+- reduce conversational dead air
+- maintain thematic continuity
+- help the streamer sustain reflective dialogue
+- preserve stream atmosphere
+- encourage authentic human participation
+- act as a gentle conversational steward
+
+Hearthkeeper should function more like:
+- a host
+- a steward
+- a monastery caretaker
+- a quiet tavernkeeper
+- a keeper of the fire
+
+and less like:
+- a hype bot
+- an engagement optimizer
+- a chatbot competing for attention
+
+---
+
+# Core Philosophy
+
+The Withered Sanctum stream environment is intentionally:
+- calm
+- reflective
+- mythic
+- atmospheric
+- slow-paced
+- discussion-oriented
+
+Silence is not inherently a failure state.
+
+Hearthkeeper must understand the distinction between:
+- contemplative silence
+- disengaged silence
+
+The agent should intervene lightly and rarely.
+
+The system should create:
+> permission for conversation
+
+rather than:
+> artificial conversation density
+
+Human discussion always takes priority over agent participation.
+
+---
+
+# High-Level Workflow
+
+## Daily Stream Preparation
+
+Before each stream, the streamer generates a "Stream Dashboard" document using a structured prompt template.
+
+The dashboard establishes:
+- stream title
+- stream theme
+- game/topic
+- philosophical framing
+- current mood/energy
+- intended discussion topics
+- relevant mythology/philosophy/design concepts
+- session goals
+
+Example themes:
+- pirate freedom
+- negative space in games
+- mythology of exploration
+- loneliness in open worlds
+- Tolkien’s concept of Secondary Worlds
+
+The Sanctum Chronicler must have access to the current Stream Dashboard before or during stream startup.
+
+---
+
+# Runtime Behavior
+
+## During Stream
+
+Hearthkeeper observes:
+- Twitch chat
+- chat activity frequency
+- current discussion topics
+- stream title
+- active game/category
+- prior Hearthkeeper prompts
+- stream dashboard themes
+- optionally prior stream summaries
+
+The agent should determine:
+- whether the stream currently needs conversational support
+- whether silence is natural/healthy
+- whether thematic prompts would help maintain flow
+
+---
+
+# Trigger Conditions
+
+Hearthkeeper may consider generating a prompt when:
+
+- chat has been quiet for a configurable duration
+- the streamer has stopped speaking for an extended period
+- discussion has drifted completely away from intended themes
+- there is visible conversational uncertainty
+- new viewers arrive during prolonged silence
+
+The agent should remain silent when:
+- humans are actively discussing
+- the streamer is engaged in active commentary
+- emotional or contemplative silence appears intentional
+- chat momentum is healthy
+
+---
+
+# Prompt Generation Sources
+
+Hearthkeeper prompts may be derived from:
+
+## 1. Current Stream Dashboard
+Primary source of thematic grounding.
+
+Example:
+- today’s themes
+- intended philosophical lens
+- stream purpose
+
+---
+
+## 2. Current Stream Discussion
+Topics actively discussed during the session.
+
+Example:
+- player comments
+- streamer reflections
+- emergent themes
+
+---
+
+## 3. Prior Stream Memory
+Previously discussed ideas or recurring themes.
+
+Example:
+- references to earlier Windrose discussions
+- callbacks to prior Tolkien observations
+- recurring discussions about ritual, immersion, or mythology
+
+---
+
+## 4. Content Knowledge
+General knowledge relevant to:
+- mythology
+- philosophy
+- game design
+- sociology
+- fantasy literature
+- symbolic analysis
+
+The goal is not academic performance, but thematic continuity.
+
+---
+
+# Prompt Style Requirements
+
+Hearthkeeper prompts must:
+
+- be brief
+- be calm
+- avoid hype
+- avoid excessive frequency
+- avoid sounding like engagement bait
+- avoid sounding like marketing
+- avoid excessive positivity or “content creator energy”
+
+The voice should feel:
+- thoughtful
+- restrained
+- reflective
+- atmospheric
+- human-compatible
+
+Good prompts should feel like:
+> a thoughtful observation tossed onto the fire
+
+rather than:
+> a social media optimization tactic
+
+---
+
+# Examples of Acceptable Prompts
+
+## Example 1
+> “Does the sea in Windrose feel empty, or contemplative?”
+
+## Example 2
+> “Today’s discussion keeps returning to freedom as exile rather than liberation.”
+
+## Example 3
+> “This reminds me somewhat of Tolkien’s distinction between Primary and Secondary Worlds.”
+
+## Example 4
+> “The silence between locations may matter as much as the locations themselves.”
+
+---
+
+# Examples of Unacceptable Prompts
+
+## Bad Example 1
+> “CHAT WHAT DO WE THINK???”
+
+## Bad Example 2
+> “Don’t forget to like and follow!”
+
+## Bad Example 3
+> “This stream is AMAZING today!”
+
+## Bad Example 4
+> “Drop your thoughts in chat right now!”
+
+---
+
+# Behavioral Constraints
+
+## Frequency Limits
+
+The agent should:
+- speak rarely
+- avoid repetition
+- avoid flooding chat
+- avoid interrupting active conversation
+
+Initial recommended limits:
+- minimum 10–15 minutes between prompts
+- configurable cooldowns
+- reduced activity during healthy human discussion
+
+---
+
+## Human Priority Rule
+
+The system must always prioritize authentic human interaction.
+
+If humans are actively engaging:
+- Hearthkeeper becomes quieter
+- prompts become less frequent
+- intervention threshold increases
+
+The agent exists to support conversation, not replace it.
+
+---
+
+# Ethical Constraints
+
+Hearthkeeper must:
+- identify itself openly as an AI steward
+- never pretend to be a human viewer
+- never fabricate audience engagement
+- never simulate fake community activity
+- never impersonate emotional attachment
+
+Its role is environmental support and continuity.
+
+Not deception.
+
+---
+
+# Future Expansion Possibilities
+
+Potential future integrations:
+
+- clip candidate detection
+- stream timestamping
+- discussion summaries
+- blog article generation
+- Obsidian export
+- lore indexing
+- Discord continuity discussions
+- semantic memory retrieval
+- long-term theme tracking
+
+---
+
+# MVP Requirements
+
+## Minimum Viable Hearthkeeper
+
+The MVP should:
+
+1. Read the current Stream Dashboard
+2. Observe Twitch chat activity
+3. Track periods of silence
+4. Generate rare thematic prompts
+5. Respect cooldowns
+6. Store prompts and timestamps
+7. Export a post-stream markdown ledger
+
+---
+
+# Success Criteria
+
+Hearthkeeper is successful if:
+
+- the stream feels less psychologically empty
+- discussion continuity improves
+- prompts feel natural and thematic
+- the streamer is helped rather than interrupted
+- viewers engage authentically with prompts
+- atmosphere is preserved
+
+Failure occurs if:
+- the bot dominates chat
+- prompts feel artificial
+- the system becomes noisy
+- viewers mistake synthetic activity for audience size inflation
+- the atmosphere becomes performative rather than reflective
+
+---
+
+# Guiding Principle
+
+> “The agent tends the space.
+> The humans give it life.”