Hugging Face's logo

Subject-Emu-5259
/
NeuralAI

Text Generation
PEFT
Safetensors
English
llama
lora
conversational
smollm2
dpo
fine-tuned
Model card Files
xet
 Community
NeuralAI / docs /BYOK_ZO_INTEGRATION.md
Subject-Emu-5259's picture
Subject-Emu-5259
sync: update docs/BYOK_ZO_INTEGRATION.md
fc680d7 verified
preview code
|
Raw
History Blame Contribute Delete
3.38 kB

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?