ws-sanctum-chronicler/prompt.md

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