Documentation
¶
Overview ¶
Package providers holds the dependency-free helpers every provider adapter shares: transport and HTTP error classification, a bounded body read, tool-use id synthesis, and price table helpers. It imports nothing outside the standard library and the runtime, so a provider SDK lives in its own module and the core stays untainted.
The classification contract matches what the runtime's accounting caller expects. A timeout is returned bare, because the request may have been received and charged and the caller must record it as ambiguous; every other failure is either a TransientError, which the caller retries, or a permanent error, which ends the run.
Index ¶
- Constants
- Variables
- func ClassifyAPIError(status int, err error) error
- func ClassifyStatus(provider string, status int, body []byte) error
- func ClassifyTransport(err error) error
- func Free(names ...string) agentrt.PriceTable
- func Merge(tables ...agentrt.PriceTable) agentrt.PriceTable
- func ParseDollars(s string) (agentrt.Micros, error)
- func PriceFor(prices agentrt.PriceTable, name string) (agentrt.Price, error)
- func ReadBody(r io.Reader) ([]byte, error)
- func SynthesizeToolUseID(i int) string
- func Transient(status int) bool
- type StatusError
Examples ¶
Constants ¶
const MaxBodyBytes = 16 << 20
MaxBodyBytes bounds how much of a provider response is read.
Variables ¶
var ErrNoPrice = errors.New("no price for this model")
ErrNoPrice is wrapped by PriceFor for a name the table does not hold. A paid model runs only with a known price.
Functions ¶
func ClassifyAPIError ¶
ClassifyAPIError classifies an SDK error that yields only a status code and the error itself. A status of zero means the SDK reported no HTTP response, so the error is a transport failure.
func ClassifyStatus ¶
ClassifyStatus converts a provider response into an error, or nil for a 2xx. A retryable status yields a TransientError wrapping a StatusError; any other non-2xx yields the StatusError itself, which is permanent.
func ClassifyTransport ¶
ClassifyTransport maps a failed HTTP round trip onto the runtime's classes. A timeout is returned bare so the accounting caller charges it as ambiguous; any other transport error is transient.
func Free ¶
func Free(names ...string) agentrt.PriceTable
Free records each name as costing nothing, which is what a local model costs. The zero prices make no difference to accounting; the entries make the difference to PriceFor.
func Merge ¶
func Merge(tables ...agentrt.PriceTable) agentrt.PriceTable
Merge combines price tables into one for agentrt.ModelConfig, so a consumer with a local and a paid model passes a single table. Later tables win.
func ParseDollars ¶
ParseDollars converts a budget written as "5", "4.41", or "$0.50" into micros, rounding to the nearest micro. Negative amounts are refused.
Example ¶
ParseDollars reads a budget as a person writes it and returns micros.
package main
import (
"fmt"
"github.com/joeylking/agent-runtime/providers"
)
func main() {
for _, s := range []string{"5", "4.41", "$0.50"} {
m, err := providers.ParseDollars(s)
fmt.Println(s, m, err)
}
}
Output: 5 5000000 <nil> 4.41 4410000 <nil> $0.50 500000 <nil>
func PriceFor ¶
PriceFor returns the price recorded for a model. A name absent from the table is an error rather than a price of zero: agentrt.PriceTable charges nothing for an unknown name, which is right for a local model and would silently defeat a budget for a paid one. Local models are recorded with Free so that "free" and "unpriced" stay distinguishable.
Example ¶
PriceFor refuses a model the table does not hold, because agentrt.PriceTable charges nothing for an unknown name and that would silently defeat a budget. Free records a local model, so free and unpriced stay distinguishable.
package main
import (
"errors"
"fmt"
"github.com/joeylking/agent-runtime/providers"
)
func main() {
prices := providers.Free("ollama:qwen3:30b-a3b")
local, err := providers.PriceFor(prices, "ollama:qwen3:30b-a3b")
fmt.Println(local.InputPerMTok, err)
_, err = providers.PriceFor(prices, "openai:a-paid-model")
fmt.Println(errors.Is(err, providers.ErrNoPrice), err)
}
Output: 0 <nil> true openai:a-paid-model: no price for this model
func ReadBody ¶
ReadBody reads at most MaxBodyBytes from r. A provider that answers with an unbounded stream cannot exhaust the process.
func SynthesizeToolUseID ¶
SynthesizeToolUseID names the ith tool use of a response for providers that return no id. Tool-use ids only have to be unique within a request, and both consumers' adapters use this form.
Types ¶
type StatusError ¶
StatusError is a provider's non-2xx response. It carries the status so a caller can act on it without matching strings.
func (StatusError) Error ¶
func (e StatusError) Error() string
Source Files
Directories