sheetnext 0.2.11 → 0.2.12

package/docs/skill/sheetnext-dev/references/ai-relay.md

@@ -1,284 +1,284 @@
-# AI Request Contract
-
-> Manual supplemental document. This file is not generated by `scripts/doc-scanner.js`.
-
-## Purpose
-
-This document describes the request data built by the SheetNext front end and the response format that the configured `AI_URL` endpoint must accept.
-
-It does not define your internal server implementation.
-
-The exact client behavior is based on `src/core/AI/AI.js`.
-
-## Client Configuration
-
-Configure the AI endpoint when creating `SheetNext`:
-
-```js
-const SN = new SheetNext(container, {
-  AI_URL: 'https://your-server.example.com/api/ai',
-  AI_TOKEN: 'optional-token'
-})
-```
-
-- `AI_URL`: required if you want to use the built-in AI runtime
-- `AI_TOKEN`: optional; when present, the browser sends `Authorization: Bearer <token>`
-
-## What the Front End Sends
-
-The front end sends an HTTP `POST` request to `AI_URL` with:
-
-- `Content-Type: application/json`
-- optional `Authorization: Bearer <token>`
-
-Request body:
-
-```json
-{
-  "messages": [
-    {
-      "role": "system",
-      "content": "System prompt text"
-    },
-    {
-      "role": "user",
-      "content": "User instruction"
-    }
-  ],
-  "tools": [
-    {
-      "type": "function",
-      "function": {
-        "name": "exampleTool",
-        "description": "Tool description",
-        "parameters": {
-          "type": "object",
-          "properties": {}
-        }
-      }
-    }
-  ],
-  "isUserStart": true
-}
-```
-
-## Request Field Meaning
-
-### `messages`
-
-This is the main Chat Completions-style message array built by the client.
-
-The front end assembles it from:
-
-- a system prompt
-- previous conversation history
-- optional attachment messages
-- a final system snapshot describing current workbook context
-
-Each message uses the usual chat structure:
-
-```json
-{
-  "role": "user",
-  "content": "plain text"
-}
-```
-
-For attachment cases, `content` can also be an array of parts:
-
-```json
-{
-  "role": "user",
-  "content": [
-    {
-      "type": "text",
-      "text": "User uploaded attachments:"
-    },
-    {
-      "type": "image_url",
-      "image_url": {
-        "url": "data:image/png;base64,..."
-      }
-    }
-  ]
-}
-```
-
-So from the server perspective:
-
-- `messages` should be accepted as-is
-- `content` may be either a string or a multimodal content array
-
-### `tools`
-
-This is the built-in tool definition array generated by SheetNext and sent together with the messages.
-
-The server should accept it as-is.
-
-If your model provider supports tool/function calling, you can forward these definitions directly or map them to your provider's equivalent format.
-
-### `isUserStart`
-
-Boolean flag:
-
-- `true`: this request starts a new user turn
-- `false`: this request is a follow-up turn in the current workflow
-
-The front end sends it for server-side flow control if needed.
-
-## What the Server Must Accept
-
-At minimum, the configured `AI_URL` endpoint should accept:
-
-```json
-{
-  "messages": "Chat Completions-style message array",
-  "tools": "SheetNext tool definitions",
-  "isUserStart": true
-}
-```
-
-In practical terms:
-
-- `messages`: required
-- `tools`: required by the current client contract
-- `isUserStart`: required by the current client contract
-
-## What the Front End Accepts Back
-
-The current client expects a streaming response and parses it as SSE-style `data:` lines.
-
-Recommended response header:
-
-```text
-Content-Type: text/event-stream
-```
-
-Stream example:
-
-```text
-data: {"type":"text","delta":"Hello"}
-
-data: {"type":"text","delta":" world"}
-
-data: [DONE]
-```
-
-Each event should be one `data: ...` line followed by a blank line.
-
-## Supported Response Chunks
-
-### `text`
-
-Append assistant text to the UI.
-
-```json
-{
-  "type": "text",
-  "delta": "Hello"
-}
-```
-
-### `tool_call`
-
-Incrementally stream a tool call. `arguments` may be partial.
-
-```json
-{
-  "type": "tool_call",
-  "tool_call": {
-    "index": 0,
-    "id": "call_1",
-    "type": "function",
-    "function": {
-      "name": "setCellValue",
-      "arguments": "{\"range\":\"A1\""
-    }
-  }
-}
-```
-
-### `tool_call_complete`
-
-Provide the completed tool call payload.
-
-```json
-{
-  "type": "tool_call_complete",
-  "tool_call": {
-    "index": 0,
-    "id": "call_1",
-    "type": "function",
-    "function": {
-      "name": "setCellValue",
-      "arguments": "{\"range\":\"A1\",\"value\":123}"
-    }
-  }
-}
-```
-
-### `usage`
-
-Optional usage information.
-
-```json
-{
-  "type": "usage",
-  "usage": {
-    "input_tokens": 1200,
-    "output_tokens": 260,
-    "total_tokens": 1460
-  }
-}
-```
-
-### `web_search`
-
-Optional status chunk recognized by the current client.
-
-```json
-{
-  "type": "web_search",
-  "status": "in_progress"
-}
-```
-
-or:
-
-```json
-{
-  "type": "web_search",
-  "status": "completed"
-}
-```
-
-### `error`
-
-Structured stream error.
-
-```json
-{
-  "error": {
-    "message": "Model request failed"
-  }
-}
-```
-
-## Error Handling
-
-- non-2xx HTTP responses are treated as request failures
-- a 2xx response can still fail by streaming an `error` payload
-- plain text or HTML error bodies are shown as error content
-- unknown chunk types are ignored by the current client
-
-## Recommended Server Strategy
-
-The simplest integration is:
-
-1. receive the JSON body from SheetNext
-2. read `messages`, `tools`, and `isUserStart`
-3. call your model service
-4. convert the model output into the SSE chunk format above
-5. stream it back to the browser
-
-As long as the server accepts the request body above and returns the chunk format above, the current SheetNext AI front end can work with it.
+# AI Request Contract
+
+> Manual supplemental document. This file is not generated by `scripts/doc-scanner.js`.
+
+## Purpose
+
+This document describes the request data built by the SheetNext front end and the response format that the configured `AI_URL` endpoint must accept.
+
+It does not define your internal server implementation.
+
+The exact client behavior is based on `src/core/AI/AI.js`.
+
+## Client Configuration
+
+Configure the AI endpoint when creating `SheetNext`:
+
+```js
+const SN = new SheetNext(container, {
+  AI_URL: 'https://your-server.example.com/api/ai',
+  AI_TOKEN: 'optional-token'
+})
+```
+
+- `AI_URL`: required if you want to use the built-in AI runtime
+- `AI_TOKEN`: optional; when present, the browser sends `Authorization: Bearer <token>`
+
+## What the Front End Sends
+
+The front end sends an HTTP `POST` request to `AI_URL` with:
+
+- `Content-Type: application/json`
+- optional `Authorization: Bearer <token>`
+
+Request body:
+
+```json
+{
+  "messages": [
+    {
+      "role": "system",
+      "content": "System prompt text"
+    },
+    {
+      "role": "user",
+      "content": "User instruction"
+    }
+  ],
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "exampleTool",
+        "description": "Tool description",
+        "parameters": {
+          "type": "object",
+          "properties": {}
+        }
+      }
+    }
+  ],
+  "isUserStart": true
+}
+```
+
+## Request Field Meaning
+
+### `messages`
+
+This is the main Chat Completions-style message array built by the client.
+
+The front end assembles it from:
+
+- a system prompt
+- previous conversation history
+- optional attachment messages
+- a final system snapshot describing current workbook context
+
+Each message uses the usual chat structure:
+
+```json
+{
+  "role": "user",
+  "content": "plain text"
+}
+```
+
+For attachment cases, `content` can also be an array of parts:
+
+```json
+{
+  "role": "user",
+  "content": [
+    {
+      "type": "text",
+      "text": "User uploaded attachments:"
+    },
+    {
+      "type": "image_url",
+      "image_url": {
+        "url": "data:image/png;base64,..."
+      }
+    }
+  ]
+}
+```
+
+So from the server perspective:
+
+- `messages` should be accepted as-is
+- `content` may be either a string or a multimodal content array
+
+### `tools`
+
+This is the built-in tool definition array generated by SheetNext and sent together with the messages.
+
+The server should accept it as-is.
+
+If your model provider supports tool/function calling, you can forward these definitions directly or map them to your provider's equivalent format.
+
+### `isUserStart`
+
+Boolean flag:
+
+- `true`: this request starts a new user turn
+- `false`: this request is a follow-up turn in the current workflow
+
+The front end sends it for server-side flow control if needed.
+
+## What the Server Must Accept
+
+At minimum, the configured `AI_URL` endpoint should accept:
+
+```json
+{
+  "messages": "Chat Completions-style message array",
+  "tools": "SheetNext tool definitions",
+  "isUserStart": true
+}
+```
+
+In practical terms:
+
+- `messages`: required
+- `tools`: required by the current client contract
+- `isUserStart`: required by the current client contract
+
+## What the Front End Accepts Back
+
+The current client expects a streaming response and parses it as SSE-style `data:` lines.
+
+Recommended response header:
+
+```text
+Content-Type: text/event-stream
+```
+
+Stream example:
+
+```text
+data: {"type":"text","delta":"Hello"}
+
+data: {"type":"text","delta":" world"}
+
+data: [DONE]
+```
+
+Each event should be one `data: ...` line followed by a blank line.
+
+## Supported Response Chunks
+
+### `text`
+
+Append assistant text to the UI.
+
+```json
+{
+  "type": "text",
+  "delta": "Hello"
+}
+```
+
+### `tool_call`
+
+Incrementally stream a tool call. `arguments` may be partial.
+
+```json
+{
+  "type": "tool_call",
+  "tool_call": {
+    "index": 0,
+    "id": "call_1",
+    "type": "function",
+    "function": {
+      "name": "setCellValue",
+      "arguments": "{\"range\":\"A1\""
+    }
+  }
+}
+```
+
+### `tool_call_complete`
+
+Provide the completed tool call payload.
+
+```json
+{
+  "type": "tool_call_complete",
+  "tool_call": {
+    "index": 0,
+    "id": "call_1",
+    "type": "function",
+    "function": {
+      "name": "setCellValue",
+      "arguments": "{\"range\":\"A1\",\"value\":123}"
+    }
+  }
+}
+```
+
+### `usage`
+
+Optional usage information.
+
+```json
+{
+  "type": "usage",
+  "usage": {
+    "input_tokens": 1200,
+    "output_tokens": 260,
+    "total_tokens": 1460
+  }
+}
+```
+
+### `web_search`
+
+Optional status chunk recognized by the current client.
+
+```json
+{
+  "type": "web_search",
+  "status": "in_progress"
+}
+```
+
+or:
+
+```json
+{
+  "type": "web_search",
+  "status": "completed"
+}
+```
+
+### `error`
+
+Structured stream error.
+
+```json
+{
+  "error": {
+    "message": "Model request failed"
+  }
+}
+```
+
+## Error Handling
+
+- non-2xx HTTP responses are treated as request failures
+- a 2xx response can still fail by streaming an `error` payload
+- plain text or HTML error bodies are shown as error content
+- unknown chunk types are ignored by the current client
+
+## Recommended Server Strategy
+
+The simplest integration is:
+
+1. receive the JSON body from SheetNext
+2. read `messages`, `tools`, and `isUserStart`
+3. call your model service
+4. convert the model output into the SSE chunk format above
+5. stream it back to the browser
+
+As long as the server accepts the request body above and returns the chunk format above, the current SheetNext AI front end can work with it.