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