Documentation
¶
Overview ¶
Package cloud is the client for the cloudproto protocol (see ai/cloudproto): it implements ai.LLMProvider (chat) and exposes a separate decision.Provider via Decider() that is also a decision.ScoredProvider (POST ai/score), plus a Usage lookup.
Index ¶
- Constants
- func WithInteractionID(ctx context.Context, id string) context.Context
- type Client
- func (c *Client) Decider() decision.Provider
- func (c *Client) Name() string
- func (c *Client) ReportInteraction(ctx context.Context, report cloudproto.InteractionReport) error
- func (c *Client) ResetCapabilities()
- func (c *Client) Stream(ctx context.Context, req ai.ChatRequest) iter.Seq2[ai.Event, error]
- func (c *Client) Usage(ctx context.Context) (cloudproto.UsageResponse, error)
- type Config
Constants ¶
const ( DefaultCapabilityTTL = 5 * time.Minute DefaultMisconfiguredTTL = 30 * time.Second )
Defaults of Config.CapabilityTTL and Config.MisconfiguredTTL.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements ai.LLMProvider (Name "cloud"). Its decision.Provider role is a SEPARATE value returned by Decider() (Name "cloud-decision"): Go dispatches one Name() per concrete type, so a single type cannot report two different names to two different interfaces, and Decider() is how that split is actually satisfied.
func New ¶
New builds a Client. It panics if BaseURL or Token is unset, and normalises BaseURL to always end with "/".
func (*Client) Decider ¶
Decider returns c's decision.Provider role (Name "cloud-decision"), backed by POST ai/decision. The value is also a decision.ScoredProvider and a decision.TracedScorer backed by POST ai/score: a hosted decision endpoint can answer scored questions (table narrowing) too. Against a server that has no ai/score route, Score returns an error wrapping decision.ErrUnsupported, so a combinator moves on to its next engine. It also implements the optional `DecisionTimeout() time.Duration` interface decision.Chain honours, so a remote decision call gets more time than Chain's local-call default.
func (*Client) ReportInteraction ¶ added in v0.4.0
func (c *Client) ReportInteraction(ctx context.Context, report cloudproto.InteractionReport) error
ReportInteraction sends one bounded, metadata-only client observation. Callers should invoke it after the user turn; a failure must not alter the result of an otherwise successful turn.
func (*Client) ResetCapabilities ¶ added in v0.6.0
func (c *Client) ResetCapabilities()
ResetCapabilities forgets what the client learned about the server: that it has no ai/score route, and that its base URL does not speak the protocol. Both verdicts expire on their own (Config.CapabilityTTL, Config.MisconfiguredTTL); call this after the server was upgraded or a base URL fixed to probe again at once.
func (*Client) Stream ¶
Stream implements ai.LLMProvider by POSTing ai/chat and parsing the SSE response with cloudproto.ReadEvents.
Fatal-error contract (see ai.LLMProvider doc): every fatal condition yields exactly one final (ai.Event{Type: ai.EventError, Error: e}, e) and returns; EventStarted is only yielded once the HTTP request has actually succeeded. cloudproto.ReadEvents already conforms (an EventError frame, a transport error, or an unterminated stream are all fatal there too), so Stream relays its events unchanged EXCEPT that a mid-stream failure caused by ctx being done (the body read was interrupted by cancellation, not a genuine transport/upstream fault) is remapped to ErrCodeCanceled here -- cloudproto has no ctx of its own to make that distinction itself.
func (*Client) Usage ¶
func (c *Client) Usage(ctx context.Context) (cloudproto.UsageResponse, error)
Usage calls GET ai/usage.
type Config ¶
type Config struct {
// BaseURL is the API base URL including its version prefix, e.g.
// "https://api.example.com/v0/". A trailing slash is added if missing.
// The product supplies this (see ai/aiconfig); this package has no
// default of its own.
BaseURL string
// Product identifies the consuming product for metering/limits/routing
// and is sent as the X-AI-Product header and ai.ChatRequest.Product /
// decision.Request.Product.
Product string
// Account and Project are optional, server-verified payer hints. A client
// must create a separate Client for each immutable selection.
Account string
Project string
// ClientContext is included in both chat and decision requests unless
// the caller provides more specific context for a particular turn.
ClientContext *ai.ClientContext
// Token returns the bearer token for each request.
Token func(context.Context) (string, error)
HTTPClient *http.Client
// CapabilityTTL is how long the client remembers that the server has no ai/score
// route (decision.ErrUnsupported) before it asks again: 0 means
// DefaultCapabilityTTL, a negative value means until ResetCapabilities. A finite
// TTL keeps one stray 404 during a rolling deploy from switching scoring off
// until restart.
CapabilityTTL time.Duration
// MisconfiguredTTL is how long a "this base URL does not speak the protocol"
// verdict (decision.ErrMisconfigured) is remembered, so a wrong base URL costs
// one probe per TTL instead of two round trips per call, and stays loud: calls
// in the window fail at once with the same error. 0 means
// DefaultMisconfiguredTTL, a negative value means do not remember it.
MisconfiguredTTL time.Duration
}
Config configures a Client.
Source Files