README.md

---
title: Ask Jerry
emoji: 🛡️
colorFrom: purple
colorTo: indigo
sdk: docker
pinned: false
app_port: 7860
---

# Ask Jerry

Single-model demo chat for the **BrainForge/Security@2026.03.18** cybersecurity model (vLLM, OpenAI-compatible API). The assistant is always **AI Jerry**; you can add optional **extra persona instructions** (similar to LLMChats freeform persona input, without renaming the bot).

**Repository:** [github.com/NeonClary/AskJerry](https://github.com/NeonClary/AskJerry)

UI styling follows the same general look as [LLMChats3](https://github.com/NeonClary/LLMChats3) (purple / indigo accents, light default).

## Docker (same pattern as [LLMComparisons](https://github.com/NeonClary/LLMComparisons))

The root `Dockerfile` builds the Vite frontend, copies `dist/` into `backend/static/`, and runs **FastAPI + Uvicorn** on port **7860** (Hugging Face Spaces default). The API serves the SPA and proxies chat to your vLLM.

```bash
docker build -t ask-jerry .
docker run --rm -p 7860:7860 \
  -e VLLM_BASE_URL=https://your-host/v1 \
  -e VLLM_API_KEY=your-key \
  -e CHAT_MODEL_ID=BrainForge/Security@2026.03.18 \
  -e CORS_ORIGINS=* \
  ask-jerry
```

Open `http://localhost:7860`.

## Hugging Face Spaces

1. Create a **Docker** Space (or connect this repo).
2. In **Settings → Repository secrets** (or Space variables), add:
   - `VLLM_BASE_URL` — OpenAI-compatible base URL including `/v1`
   - `VLLM_API_KEY` — bearer token for vLLM (if required)
   - Optional: `CHAT_MODEL_ID`, `CORS_ORIGINS` (defaults to `*` in the image for HF; override if needed)

Secrets are injected as environment variables at runtime; do **not** commit `.env` to git.

### Create the Space from the Hub CLI (optional)

Install the CLI (`pip install huggingface_hub`), set `HF_TOKEN` to a token with write access, then:

```bash
python -m huggingface_hub.cli.hf repos create neongeckocom/AskJerry --type space --space-sdk docker --public --exist-ok
```

Replace `neongeckocom/AskJerry` with your org/username and desired Space name. Then add this repo as a **git remote** and push, or use **Settings → Connect to GitHub** on the Space to deploy from [NeonClary/AskJerry](https://github.com/NeonClary/AskJerry).

## Requirements

- Python 3.11+
- Node.js 20+
- A running vLLM server that exposes `POST /v1/chat/completions` for `BrainForge/Security@2026.03.18` (or override `CHAT_MODEL_ID`).

## Setup

### Backend

```bash
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
```

On Windows, if `pip install` reports packages under a path that is not `...\backend\.venv\...`, use `python -m pip install -r requirements.txt` so dependencies install into the venv you activated.

Edit `.env` and set:

- `VLLM_BASE_URL` — base URL including `/v1` (example: `http://your-host:port/v1`)
- `VLLM_API_KEY` — bearer token your vLLM expects (see `.env.example` for BrainForge/Security notes)
- `CHAT_MODEL_ID` — defaults to `BrainForge/Security@2026.03.18`

### Frontend

```bash
cd frontend
npm install
```

## Run (development)

**Canonical repo:** use a single local clone of this repository (avoid duplicate checkouts serving different ports).

Uses **port 3006** for the Vite dev server and **8006** for the API so it does not conflict with typical 3000/5173/8080 stacks.

Quick reference: `scripts\start-dev.ps1` prints the two terminal commands.

**Terminal 1 — API**

```bash
cd backend
.venv\Scripts\activate
uvicorn app.main:app --host 127.0.0.1 --port 8006
```

**Terminal 2 — UI**

```bash
cd frontend
npm run dev
```

Open **http://localhost:3006**. The dev server proxies `/api` and `/health` to `http://127.0.0.1:8006`.

You can override ports with **`ASKJERRY_DEV_PORT`** (Vite) and **`ASKJERRY_API_PORT`** (proxy target and implied API port you pass to uvicorn).

### Parallel local stacks (`FEAT_STT-TTS` + `master`)

To run the **voice** branch and **master** at the same time, use a second checkout (recommended: **git worktree**) and **different ports** so nothing collides.

**1. One-time: add a worktree for `master` next to your main clone**

From your main repo (e.g. on `FEAT_STT-TTS`):

```bash
cd path\to\AskJerry
git fetch origin
git worktree add ..\AskJerry-master master
```

**2. Install dependencies in both folders** (`backend`: venv + `pip install -r requirements.txt`; `frontend`: `npm install`). Copy `backend\.env.example` → `backend\.env` in each worktree; point both at the same vLLM if you like.

**3. Port split (default convention)**

| Stack | Branch | UI | API |
|--------|--------|-----|-----|
| Main folder | `FEAT_STT-TTS` | 3006 | 8006 |
| `AskJerry-master` | `master` | 3007 | 8007 |

**4. Run**

In the **FEAT** repo — Terminal A: `cd backend` → activate venv → `uvicorn app.main:app --host 127.0.0.1 --port 8006`. Terminal B: `cd frontend` → `npm run dev` → open **http://localhost:3006**.

In **`AskJerry-master`** — Terminal A: `uvicorn ... --port 8007`. Terminal B: `npm run dev:alt` → open **http://localhost:3007**.

In **`AskJerry-master`** `backend\.env`, set `CORS_ORIGINS` to include `http://localhost:3007` and `http://127.0.0.1:3007` (the FEAT stack can keep `3006` only).

The `dev:alt` script sets `ASKJERRY_DEV_PORT=3007` and `ASKJERRY_API_PORT=8007`. The same port configuration is on **`master`** (pushed as of the “configurable dev ports” commit).

### Voice (STT / TTS)

The API proxies **Coqui TTS** and **Whisper STT** (defaults: `coqui.neonaiservices.com`, `whisper.neonaiservices.com`). Override with `COQUI_BASE_URL` and `WHISPER_BASE_URL` in `.env`.

- **TTS:** `POST /api/tts` with JSON `{ "text": "..." }` returns `audio/wav`.
- **STT:** `POST /api/transcribe` with multipart field `audio` (e.g. WebM from the browser); requires **ffmpeg** on the server (included in the Docker image).

Local dev: install backend deps (`pip install -r requirements.txt`) and ensure **ffmpeg** is on your PATH for speech-to-text conversion.

## Features

- **Additional persona instructions** — optional text merged into the system prompt under “Additional instructions from the user” (name remains AI Jerry).
- **Stop** — aborts the current stream (partial reply is kept).
- **Refresh** — regenerates the last assistant reply (same last user message).
- **New chat** — clears the thread (aborts if streaming).
- **Read aloud** — speaker icon on each assistant message (TTS); **Always speak responses** in Options.
- **Mic input** — microphone next to Send records speech and appends transcribed text (STT).

## Clone

```bash
git clone https://github.com/NeonClary/AskJerry.git
cd AskJerry
```