Documentation
¶
Overview ¶
Package cloudproto is the small, product-neutral wire protocol between clients and an AI cloud boundary. It is OpenAI-inspired and event-oriented but deliberately NOT a provider's protocol: upstream providers (and any gateway such as Cloudflare AI Gateway behind the boundary) can change without changing this contract. The cloud boundary's base URL is supplied by the product (see ai/cloud.Config.BaseURL / ai/aiconfig); this package has no default of its own.
POST {base}ai/chat body: ai.ChatRequest → text/event-stream of ai.Event
POST {base}ai/decision body: decision.Request → application/json DecisionResponse
GET {base}ai/usage → application/json UsageResponse
{base} is the API base URL including its version prefix, e.g. https://api.example.com/v0/. Requests carry the product's normal bearer authentication and the X-AI-Product header.
SSE framing: each ai.Event is sent as
event: <ai.Event.Type> data: <ai.Event as single-line JSON> <blank line>
Unknown event names must be ignored by clients. The stream ends after response.completed or a fatal error event (see ai.LLMProvider's fatal-error contract, which ReadEvents follows: an EventError frame is always fatal on this wire and ReadEvents stops after yielding it). Errors before streaming starts are ordinary HTTP errors with an ErrorResponse JSON body.
Index ¶
Constants ¶
const ( PathChat = "ai/chat" PathDecision = "ai/decision" PathUsage = "ai/usage" PathInteraction = "ai/interactions" HeaderProduct = "X-AI-Product" ContentTypeSSE = "text/event-stream" )
Variables ¶
This section is empty.
Functions ¶
func ReadEvents ¶
ReadEvents parses an SSE stream of ai.Event. It yields events as soon as each frame completes (no buffering of the whole response), skips comments and unknown event names, and stops after response.completed or after a fatal error.
On this wire, an EventError frame is always fatal: ReadEvents yields it as the fatal pair (ev, err) with err a non-nil *ai.Error built from ev.Error, per the ai.LLMProvider contract, and returns immediately afterward. A transport EOF that arrives before either response.completed or an error frame was seen is itself a fatal truncation and is reported the same way.
Types ¶
type ActionExecution ¶ added in v0.4.0
type DecisionResponse ¶
type DecisionResponse struct {
Decided bool `json:"decided"`
Decision decision.Decision `json:"decision,omitzero"`
Model string `json:"model,omitempty"`
Usage *ai.Usage `json:"usage,omitempty"`
}
DecisionResponse is the body of POST ai/decision.
type DetectionStep ¶ added in v0.4.0
type DetectionStep struct {
Method string `json:"method"`
Detector string `json:"detector,omitempty"`
Version string `json:"version,omitempty"`
Result string `json:"result,omitempty"`
Actions []string `json:"actions,omitempty"`
Domains []string `json:"domains,omitempty"`
Confidence *float64 `json:"confidence,omitempty"`
}
DetectionStep and ActionExecution are client-observed facts.
type ErrorResponse ¶
ErrorResponse is the JSON body of a non-2xx response.
type InteractionReport ¶ added in v0.4.0
type InteractionReport struct {
InteractionID string `json:"interactionId"`
Product string `json:"product"`
ClientContext *ai.ClientContext `json:"clientContext,omitempty"`
UserMessageChars int `json:"userMessageChars"`
UserMessageWords int `json:"userMessageWords"`
UserMessageTokens *int `json:"userMessageTokens,omitempty"`
DetectionSteps []DetectionStep `json:"detectionSteps,omitempty"`
ActionExecutions []ActionExecution `json:"actionExecutions,omitempty"`
Status string `json:"status"`
Outcome string `json:"outcome,omitempty"`
RetryOfInteraction string `json:"retryOfInteractionId,omitempty"`
WasRegenerated bool `json:"wasRegenerated,omitempty"`
WasCancelled bool `json:"wasCancelled,omitempty"`
}
InteractionReport records an observable user turn, including turns handled entirely by deterministic client logic. User identity is never supplied.
type UsageResponse ¶
type UsageResponse struct {
Product string `json:"product"`
Allowance *ai.Allowance `json:"allowance,omitempty"`
}
UsageResponse is the body of GET ai/usage.
Source Files