# 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.