File size: 3,381 Bytes
fc680d7 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 | # 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?`
|