64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# ADHDbot
|
||
|
||
## Quick Start
|
||
|
||
1. Copy the example environment file and fill in your secrets:
|
||
```bash
|
||
cp .env.example .env
|
||
# edit .env to insert your real OPENROUTER_API_KEY, DISCORD_BOT_TOKEN, TARGET_USER_ID, etc.
|
||
```
|
||
2. Bring up the stack with docker-compose (recommended; includes host persistence for logs/notes):
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
- `./memory` is bind-mounted into the container (`./memory:/app/memory`), so any saved notes appear in the repo directly.
|
||
- `.env` is auto-loaded and the FastAPI service is exposed on `http://localhost:8000`.
|
||
3. Or build/run manually if you prefer the raw Docker commands:
|
||
```bash
|
||
docker build -t adhdbot .
|
||
docker run --rm -p 8000:8000 --env-file .env -v "$PWD/memory:/app/memory" adhdbot
|
||
```
|
||
|
||
### API usage
|
||
|
||
Once the container is running, hit the API to trigger a prompt flow:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/run \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"userId": "chelsea",
|
||
"category": "general",
|
||
"promptName": "welcome",
|
||
"context": "Take a note that the user is testing the system you're being called from"
|
||
}'
|
||
```
|
||
|
||
Endpoints:
|
||
- `GET /health` – simple liveness check.
|
||
- `POST /run` – triggers `Runner.run`; pass `userId`, `category`, `promptName`, and `context` to override defaults from `.env`.
|
||
|
||
Environment variables of interest (see `.env.example`):
|
||
- `OPENROUTER_API_KEY` – OpenRouter key used by `AIInteraction`.
|
||
- `DISCORD_BOT_TOKEN` / `TARGET_USER_ID` / `DISCORD_WEBHOOK_URL` – Discord plumbing.
|
||
- `PROMPT_CATEGORY`, `PROMPT_NAME`, `PROMPT_CONTEXT` – defaults for the `/run` endpoint.
|
||
- `LOG_PROMPTS` (default `1`) – when truthy, every outgoing prompt is logged to stdout so you can audit the final instructions sent to the LLM.
|
||
|
||
## Prompt + tooling customization
|
||
|
||
- All templates live in `prompts/defaultPrompts.json` (and sibling files). Edit them and restart the service to take effect.
|
||
- Shared tooling instructions live in `prompts/tool_instructions.md`. `AIInteraction` injects this file both into the **system prompt** and at the end of every user prompt, so any changes immediately affect how models emit `take_note`, `store_task`, or `schedule_reminder` JSON payloads.
|
||
- `PROMPTS.md` documents each category plus examples of the structured JSON outputs that downstream services can parse.
|
||
|
||
### Memory + notes
|
||
|
||
- The memory subsystem watches LLM responses for fenced ```json payloads. When it sees `{"action": "take_note", ...}` it writes to `memory/<user>_memory.json` (now persisted on the host via the compose volume).
|
||
- Each entry includes the note text, UTC timestamp, and the raw metadata payload, so other services can build summaries or downstream automations from the same file.
|
||
|
||
### Debugging tips
|
||
|
||
- Tail the container logs with `docker compose logs -f adhdbot` to see:
|
||
- The final prompt (with tooling contract) sent to the model.
|
||
- Memory ingestion messages like `[memory] Recorded note for <user>: ...`.
|
||
- If you swap models, change `openRouterModel` in `AIInteraction.py` (or surface it via env) and rebuild the container.
|