173 lines
3.7 KiB
Markdown
173 lines
3.7 KiB
Markdown
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 |