first commit

README.md

@@ -0,0 +1,63 @@
+# 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.