Implement runtime agent loop and container hygiene

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