Workspace inference results and streaming protocol¶
Ordinary chat results¶
Field |
Type |
Description |
|---|---|---|
id |
string |
Completion identifier; presence depends on the provider adapter. |
model |
string |
Returned model identifier. |
choices |
object (array of objects) |
Provider-compatible candidate results. |
choices[].index |
integer |
Candidate index. |
choices[].message |
object |
Response message; may contain role/content and tool calls. |
choices[].finish_reason |
string or null |
Provider-supplied finish reason. |
usage |
object |
Provider-reported usage; may be absent. Absence does not mean free or zero usage. |
moi_context_budget |
object |
Added by the gateway only when budget checking is enabled. |
moi_context_budget.status |
string |
checked or unknown. |
moi_context_budget.input_tokens |
integer |
Measured input token count when checked. |
moi_context_budget.context_window |
integer |
Measured context capacity when checked. |
moi_context_budget.reserved_output_tokens |
integer |
Reserved output tokens when checked. |
moi_context_budget.reason |
string |
Reason when unknown, such as adapter_unsupported. |
This is a compatible format. Raw providers and adapters may return extra fields; the example is not a mandatory, complete, unified schema. Ordinary responses have no product code envelope.
Embedding results¶
Field |
Type |
Description |
|---|---|---|
object |
string |
Typically list. |
data |
object (array of objects) |
The vector result itself; do not unwrap another product data envelope. |
data[].object |
string |
Typically embedding. |
data[].embedding |
number (array of numbers) |
Numeric vector; length depends on the model. |
data[].index |
integer |
Input association index. Batched paths rewrite returned entries to globally consecutive indices; arbitrary upstream reordering/missing entries may not be recoverable. |
model |
string |
Provider model identifier; taken from the first batch for batched calls. |
usage |
object |
Provider usage. Batch merging may sum numeric fields and retain other metadata; shape depends on the provider. |
Ordinary public Embedding calls currently do not enable the internal knowledge-retrieval checks for entry count/nonempty vectors. After 200, still verify result count, index, dimensions, and model against consumer requirements. One successful batch does not establish all batching/encoding behavior.
SSE streams¶
data: {"choices":[{"delta":{"content":"你好"}}]}
data: [DONE]
Accumulate delta across events. Do not decode an entire stream as one JSON object. Once 200 is sent, the handler cannot change HTTP status on error and may return:
event: error
data: {"error":{"message":"upstream failed"}}
SDK streaming returns a readable response body; CLI outputs raw SSE. They do not necessarily parse event:error automatically. Identify error events and completion signals. HTTP200 or CLI exit 0 alone does not establish a complete answer. Disconnection/cancellation may simply close the connection; treat a missing completion signal as incomplete and do not blindly retry generation.
Errors and completion conditions¶
Situation |
HTTP/numeric code |
Description |
|---|---|---|
Invalid input |
400/2 |
Invalid model/JSON/budget and stream combinations, Embedding inputs, and similar conditions. |
Budget exceeded |
422/2 |
Context budget exceeds context capacity; this does not mean an answer was generated. |
Request/resource limits |
413/14 |
Embedding body, input count, upstream-read, or call-budget limits exceeded. |
No available route |
503/1 |
No backend/endpoint is available for the current model. |
Budget or billing dependencies unavailable |
503/15 |
Do not interpret this as missing usage after success. |
Configuration/adapter/chat provider failure |
500/1 |
May include details.cause and details.upstream_status. The upstream status is string diagnostics, not a replacement for the current HTTP status. |
Embedding provider error |
Upstream 4xx/5xx or 500, code1 |
Returns an identifiable upstream status and sanitized reason, separately from Chat’s fixed 500 mapping. |
Billing admission rejected |
402/14, 403/5, or dependency 503/15 |
Details include reason/retryable and optional action. Messages may be localized; this is not a provider error tag. |
API errors use code/message with optional details. Identity or runtime-proof boundaries may instead use string code/msg. Do not decode ordinary success, errors, SSE error events, and Genesis error envelopes as one format. Completed provider responses and settlement states are distinct. Actual billing/compensation and environment configuration still require retesting.
Diagnostic field |
Type |
Description |
|---|---|---|
details.cause |
string |
Optional sanitized reason, mainly for provider errors. |
details.upstream_status |
string |
Optional upstream HTTP status diagnostics. |
details.reason |
string |
Stable reason code for billing admission rejection. |
details.retryable |
string |
true/false strings for billing admission, not JSON booleans. |
details.action |
string |
Optional recovery action code for billing admission. |