# NeuralAI ↔ ZO Computer (BYOK) Integration

## What this is
NeuralAI exposes an OpenAI-compatible API (the **BYO API** feature) so it can act as a
custom model provider inside other chat UIs. This is **verified working** with
**ZO Computer's Bring Your Own Key (BYOK)**.

End-to-end test (2026-07-15): in ZO chat, user sent `hello` → NeuralAI replied
`Hello! How can I help you today?`

## Live endpoints
- **Base URL:** `https://neuralai-web-ui-deandrewharris.zocomputer.io/v1`
- **Model id:** `neuralai`
- `GET  /v1/models` → OpenAI-style model list
- `POST /v1/chat/completions` → chat (SSE streaming by default; JSON when `stream:false`)
- `GET  /v1/chat/completions` → `200` health/capability probe (added so BYOK validation passes)

## Authentication
Generate a personal API key inside the NeuralAI Web Chat UI:
**Settings → Developer / API Access (BYO API) → Generate API Key**.

- The key (`nai_…`) is shown **once**, stored hashed (`sha256`) in `data/neuralai.db`
  (`user_settings` table), and is revocable from the same panel.
- Send it as `Authorization: Bearer <key>`. Also accepted: `?api_key=<key>`,
  `X-Api-Key: <key>`, or a `api_key` field in the JSON body.
- Fallback: if the request carries ZO's platform identity token it resolves to the
  founder account, so the call never 401s through ZO's gateway.

## ZO Computer setup
1. In the NeuralAI Web Chat UI, generate the BYO API key and copy it.
2. In ZO Computer: **Settings → AI → Providers → Bring Your Own Key**.
3. Add a custom OpenAI-compatible endpoint:
   - **Base URL:** `https://neuralai-web-ui-deandrewharris.zocomputer.io/v1`
   - **API Key:** the `nai_…` key from step 1
   - **Model:** `neuralai`
4. Select `neuralai` in ZO chat and start talking.

## Compatibility notes
- **CORS** is enabled on all `/v1/*` responses (OpenAI-compatible: `Access-Control-Allow-Origin: *`,
  `Allow-Methods: GET, POST, OPTIONS`, `Allow-Headers: Authorization, Content-Type, X-Api-Key`)
  so browser-side and proxy calls both succeed.
- **Streaming + non-streaming**: defaults to SSE; honors the request `stream` flag and
  returns a single `chat.completion` JSON object when `stream: false`.
- **GET validation probe**: ZO's BYOK issues a `GET` to the endpoint during setup.
  The `/v1` and `/v1/chat/completions` routes now return `200` (model list) for `GET`,
  which prevents a `405 Method Not Allowed` from blocking validation.

## Where the code lives
- `services/webui_service.py` — `openai_chat_completions` (POST, streaming/JSON) and
  `openai_chat_completions_get` (GET probe), plus the CORS `after_request` hook
  (`_add_cors_headers`) and the `_streaming_response` helper.
- UI: `from-scratch/web_ui/templates/index.html` — the BYO API card shows the Base URL
  to paste into ZO's BYOK field and the model name `neuralai`.

## Backend
Served by `services/webui_service.py` (entrypoint `run_service.sh`). Currently backed by
the local **SmolLM2-360M** via LM Studio on `:1234`, so responses are lightweight — the
OpenAI-compatible plumbing is production-grade, the model itself is small.

## Verification (2026-07-15)
- `GET /v1` → 200
- `GET /v1/chat/completions` → 200 (model list JSON)
- `OPTIONS /v1/chat/completions` → 200 (CORS preflight)
- `POST /v1/chat/completions` (stream) → SSE deltas
- ZO chat end-to-end: `hello` → `Hello! How can I help you today?`