# Image Moderation Service

TypeScript/Express service that checks uploaded images for NSFW/explicit content using a local vision LLM running on an AMD NPU. When an image is flagged unsafe, it fires callbacks to replace the image and flag the user.

## How It Works

1. An image is uploaded to `POST /moderate`
2. The image is sent to the local vision LLM (gemma3:4b via FLM proxy) for analysis
3. The LLM classifies the image as safe or unsafe
4. If unsafe and metadata was provided, two callbacks fire (fire-and-forget):
   - **Upload service** — replaces the image with a stub
   - **Parochia** — flags the user for moderation

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/moderate` | Moderate an image (multipart: `file`, `context`, `imagePath`, `userId`, `siteId`) |
| `GET` | `/health` | Health check |

## Configuration

All configuration is via environment variables (`.env` file):

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8100` | Service port |
| `VISION_AI_URL` | `http://localhost:8000/v1/chat/completions` | Vision LLM endpoint |
| `VISION_AI_MODEL` | `gemma3:4b` | Vision model to use |
| `UPLOAD_SERVICE_REPLACE_URL` | — | Callback URL to replace flagged images |
| `UPLOAD_SERVICE_SECRET` | — | Auth secret for upload service callback |
| `PAROCHIA_CALLBACK_URL` | — | Callback URL to flag users in Parochia |
| `PAROCHIA_CALLBACK_SECRET` | — | Auth secret for Parochia callback |

## Usage

```bash
npm install        # Install dependencies
npm run build      # Compile TypeScript → dist/
npm start          # Run the service
npm run dev        # Development mode with hot-reload

# Windows service
node service-install.js
node service-uninstall.js
```

## Project Structure

```
src/
  server.ts      — Express app, routes, callback logic
  moderate.ts    — Image moderation logic (vision LLM calls)
```

## Dependencies

- **express** — HTTP server
- **multer** — Multipart file upload handling
- **sharp** — Image processing
- **dotenv** — Environment variable loading
- **node-windows** — Windows service management

## Environment

- **OS:** Windows 11, AMD NPU hardware
- **Runtime:** Node.js + TypeScript
- **Vision LLM:** gemma3:4b served by FLM proxy on localhost:8000