mirror of
https://github.com/hanzo-go/sdk.git
synced 2026-11-20 20:13:42 +00:00
179 lines
6.9 KiB
Go
179 lines
6.9 KiB
Go
// Usage limits: the refusal a plan or a wallet answers with, and the headers an
|
|
// AI answer carries about where its class stands. Hand-written beside the
|
|
// generated client, like hanzo.go, under the names the JS and Python SDKs use.
|
|
//
|
|
// _, resp, err := client.AiAPI.PostDecisions(ctx).AiDecisionsRequest(req).Execute()
|
|
// if errors.Is(err, hanzoai.ErrFreePlanCap) { ... }
|
|
// var ule *hanzoai.UsageLimitError
|
|
// if errors.As(err, &ule) { fmt.Println(ule.ResetsAt, ule.Actions) }
|
|
// fmt.Println(hanzoai.ReadUsage(resp.Header).Usage)
|
|
//
|
|
// GET /v1/ai/limits (client.AiAPI.AiLimits) answers where every class stands;
|
|
// PUT /v1/ai/limits (AiSetLimits) turns credits after the allowance on or off.
|
|
package hanzoai
|
|
|
|
import (
|
|
"encoding/json"
|
|
"errors"
|
|
"net/http"
|
|
"strconv"
|
|
"strings"
|
|
)
|
|
|
|
// The refusal codes a plan or a wallet answers with, in the body's error.code.
|
|
const (
|
|
// CodePlanAllowanceUsed: the plan's included usage of the model's class is
|
|
// used and nothing else may pay. 402.
|
|
CodePlanAllowanceUsed = "plan_allowance_used"
|
|
// CodePaidPlanRequired: the model needs a paid plan or prepaid balance. 402.
|
|
CodePaidPlanRequired = "paid_plan_required"
|
|
// CodeFreePlanCap: the free plan's daily cap on the model is used. 429,
|
|
// with Retry-After.
|
|
CodeFreePlanCap = "free_plan_cap"
|
|
// CodeModelCap: the model used its share of the plan; Fallback names the
|
|
// model that answers instead. 402.
|
|
CodeModelCap = "model_cap"
|
|
// CodeUsageCapExceeded: a session or day request window is spent. 429.
|
|
CodeUsageCapExceeded = "usage_cap_exceeded"
|
|
// CodeInsufficientBalance: the wallet's known balance cannot cover the
|
|
// request. 402.
|
|
CodeInsufficientBalance = "insufficient_balance"
|
|
)
|
|
|
|
// One sentinel per code. errors.Is(err, ErrModelCap) holds for any error a
|
|
// generated method returns whose body carries that code.
|
|
var (
|
|
ErrPlanAllowanceUsed = errors.New("hanzoai: " + CodePlanAllowanceUsed)
|
|
ErrPaidPlanRequired = errors.New("hanzoai: " + CodePaidPlanRequired)
|
|
ErrFreePlanCap = errors.New("hanzoai: " + CodeFreePlanCap)
|
|
ErrModelCap = errors.New("hanzoai: " + CodeModelCap)
|
|
ErrUsageCapExceeded = errors.New("hanzoai: " + CodeUsageCapExceeded)
|
|
ErrInsufficientBalance = errors.New("hanzoai: " + CodeInsufficientBalance)
|
|
)
|
|
|
|
// limits is each code's sentinel and the status the gateway sends it with.
|
|
var limits = map[string]struct {
|
|
err error
|
|
status int
|
|
}{
|
|
CodePlanAllowanceUsed: {ErrPlanAllowanceUsed, http.StatusPaymentRequired},
|
|
CodePaidPlanRequired: {ErrPaidPlanRequired, http.StatusPaymentRequired},
|
|
CodeFreePlanCap: {ErrFreePlanCap, http.StatusTooManyRequests},
|
|
CodeModelCap: {ErrModelCap, http.StatusPaymentRequired},
|
|
CodeUsageCapExceeded: {ErrUsageCapExceeded, http.StatusTooManyRequests},
|
|
CodeInsufficientBalance: {ErrInsufficientBalance, http.StatusPaymentRequired},
|
|
}
|
|
|
|
// UsageLimitError is a request a plan or a wallet refused. errors.As reaches it
|
|
// through the *GenericOpenAPIError every generated method returns.
|
|
//
|
|
// Chat from an API key is refused rather than answered by a fallback model
|
|
// unless the client asks for the fallback:
|
|
//
|
|
// client.GetConfig().AddDefaultHeader("X-Hanzo-Fallback", "allow")
|
|
type UsageLimitError struct {
|
|
Status int // 402 or 429
|
|
Code string // one of the Code constants
|
|
Type string // billing_error or rate_limit_error
|
|
Message string // the sentence to show a person
|
|
Class string // premium, ours or free
|
|
Model string // the model refused
|
|
Fallback string // the model that answers instead (model_cap)
|
|
ResetsAt string // RFC 3339, when it lifts by itself; "" when it does not
|
|
UpgradeURL string // the plan that raises it
|
|
Actions []UsageAction // the ways on
|
|
}
|
|
|
|
// UsageAction is one way past a refusal.
|
|
type UsageAction struct {
|
|
Kind string `json:"kind"` // upgrade, switch, credits or topup
|
|
Label string `json:"label"`
|
|
// URL is the page for upgrade and topup, and /v1/ai/limits for credits:
|
|
// AiSetLimits with creditsAfterAllowance turns them on.
|
|
URL string `json:"url,omitempty"`
|
|
Plan string `json:"plan,omitempty"` // upgrade
|
|
Model string `json:"model,omitempty"` // switch
|
|
}
|
|
|
|
func (e *UsageLimitError) Error() string {
|
|
return "hanzoai: " + strconv.Itoa(e.Status) + " " + e.Code + ": " + e.Message
|
|
}
|
|
|
|
// Unwrap answers the code's sentinel, which is what errors.Is compares.
|
|
func (e *UsageLimitError) Unwrap() error { return limits[e.Code].err }
|
|
|
|
// Unwrap answers the usage refusal the body carries, or nil, so errors.Is and
|
|
// errors.As see a UsageLimitError through any generated method's error.
|
|
func (e GenericOpenAPIError) Unwrap() error {
|
|
if u := usageLimit(e.error, e.body); u != nil {
|
|
return u
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// usageLimit reads a refusal body. line is the generated error's text, which
|
|
// begins with the status line unless decoding the body into the operation's own
|
|
// error schema failed; then the code's status stands in for it.
|
|
func usageLimit(line string, body []byte) *UsageLimitError {
|
|
var b struct {
|
|
Error *struct {
|
|
Message string `json:"message"`
|
|
Type string `json:"type"`
|
|
Code string `json:"code"`
|
|
Class string `json:"class"`
|
|
Model string `json:"model"`
|
|
Fallback string `json:"fallback"`
|
|
ResetsAt string `json:"resets_at"`
|
|
UpgradeURL string `json:"upgrade_url"`
|
|
Actions []UsageAction `json:"actions"`
|
|
} `json:"error"`
|
|
}
|
|
if json.Unmarshal(body, &b) != nil || b.Error == nil {
|
|
return nil
|
|
}
|
|
known, ok := limits[b.Error.Code]
|
|
if !ok {
|
|
return nil
|
|
}
|
|
status, err := strconv.Atoi(strings.SplitN(line, " ", 2)[0])
|
|
if err != nil || status < 100 || status > 599 {
|
|
status = known.status
|
|
}
|
|
return &UsageLimitError{
|
|
Status: status,
|
|
Code: b.Error.Code,
|
|
Type: b.Error.Type,
|
|
Message: b.Error.Message,
|
|
Class: b.Error.Class,
|
|
Model: b.Error.Model,
|
|
Fallback: b.Error.Fallback,
|
|
ResetsAt: b.Error.ResetsAt,
|
|
UpgradeURL: b.Error.UpgradeURL,
|
|
Actions: b.Error.Actions,
|
|
}
|
|
}
|
|
|
|
// Usage is where an answer's class stands, read off its headers. An absent
|
|
// header reads "".
|
|
type Usage struct {
|
|
Usage string // X-Hanzo-Usage: ok, near or limited
|
|
Class string // X-Hanzo-Usage-Class: premium, ours or free
|
|
PaidBy string // X-Hanzo-Paid-By: plan, credits or free
|
|
Fallback string // X-Hanzo-Fallback: the model that answered instead
|
|
Served string // X-Hanzo-Served: the Hanzo SKU that answered
|
|
Reason string // X-Hanzo-Usage-Reason: the refusal code that caused the fallback
|
|
}
|
|
|
|
// ReadUsage reads the usage headers off an answer: resp.Header from any
|
|
// Execute, refused or not.
|
|
func ReadUsage(h http.Header) Usage {
|
|
return Usage{
|
|
Usage: h.Get("X-Hanzo-Usage"),
|
|
Class: h.Get("X-Hanzo-Usage-Class"),
|
|
PaidBy: h.Get("X-Hanzo-Paid-By"),
|
|
Fallback: h.Get("X-Hanzo-Fallback"),
|
|
Served: h.Get("X-Hanzo-Served"),
|
|
Reason: h.Get("X-Hanzo-Usage-Reason"),
|
|
}
|
|
}
|