magpieplugin

package
v0.0.0-...-8a5ce65 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: GPL-3.0, LGPL-3.0 Imports: 23 Imported by: 0

Documentation

Overview

Package magpieplugin handles Magpie provider plugin packages independently of comic sources. It understands package entry paths, not provider hooks yet. Network, archive decoding, authentication and JavaScript execution belong to callers or later runtime layers.

Sending a conversation to whichever endpoint answers, and stopping when a retry would contradict what the reader already saw.

Sending a conversation through the package that owns the vendor.

Magpie's provider plugins do not hand over headers: their loader refreshes the account and returns a `fetch` that carries the sign-in, so the request has to go through the package. This calls that fetch and reads the reply as it arrives, without the client learning the vendor's shape.

The daily check-in a plugin may press itself.

Magpie asks each account once a day while the switch is on, and a plugin answers with one of a few outcomes. The set is fixed so a client can say what happened without parsing a vendor's sentence; an outcome outside it is a failure that names what the plugin actually answered.

Loader compiles a Magpie provider package for MoeJS. It resolves only package-relative modules: a Node built-in or npm dependency fails here instead of resolving to an empty stub, so a package the host cannot run says so before any hook is called.

The models a provider offers, asked for rather than assumed.

Magpie keeps a catalogue of model names per provider, because its gateway wants context sizes up front. A client only needs what it can actually pick, so this asks the vendor that already knows: an OpenAI-compatible `/models` answer. A provider that does not answer gets a plain "it does not say", never a list invented here.

The plugin a provider package exports, reached without the client writing JavaScript.

A Magpie provider package exports a function — default, or any named export — which Magpie calls with an `input` object and which answers with `{auth: {provider, methods, loader, usage, options}}`. A client that wants a sign-in would otherwise have to reproduce that ABI in its own language; this bridge keeps the ABI in one place, next to the runtime that already knows how to await it.

Stream events from a provider to our own message model. A provider plugin speaks whichever API its vendor does; this turns the three dialects Magpie serves into the same small set of events, so the client never parses a vendor's JSON.

A provider's usage as Magpie reports it, whatever shape its vendor answered.

A package's `auth.usage` returns its vendor's own numbers; Magpie normalises them and so does this, rule for rule: a value the vendor did not give must stay unsaid rather than become zero, because "0% used" and "I cannot tell" read very differently on a quota card.

Index

Constants

View Source
const (
	KindRelative = "relative" // resolved inside the package
	KindNode     = "node"     // a Node built-in, needs a host adapter
	KindBare     = "bare"     // an npm dependency, must be installed or bundled
	KindURL      = "url"      // an absolute URL import, never loadable offline
)

External kinds, as a report tells them apart.

View Source
const (
	MaxFiles      = 1024
	MaxFileBytes  = 8 << 20
	MaxTotalBytes = 32 << 20
)
View Source
const DefaultMemoryLimit int64 = 64 << 20

DefaultMemoryLimit bounds one plugin instance. Providers hold model lists and streamed replies, so the limit is generous but finite.

View Source
const MaxModules = 512

MaxModules bounds one package's reachable module graph.

Variables

View Source
var (
	ErrInvalidPath       = errors.New("magpieplugin: invalid package path")
	ErrLimit             = errors.New("magpieplugin: package exceeds limits")
	ErrNoEntry           = errors.New("magpieplugin: no loadable entry")
	ErrUnsupportedModule = errors.New("magpieplugin: module requires a host adapter or bundled dependency")
	// ErrUnsupportedSource means the package ships a language this runtime does
	// not read, such as TypeScript.
	ErrUnsupportedSource = errors.New("magpieplugin: unsupported source language")
)
View Source
var ErrNoRetryAfterOutput = errors.New("magpieplugin: output has started, so this attempt cannot be retried")

ErrNoRetryAfterOutput says an attempt may not be handed to another vendor: the reader has already been shown part of the reply, and trying again would either repeat it or contradict it.

View Source
var ErrNotAnArchive = errors.New("magpieplugin: not a zip or tar.gz package")

ErrNotAnArchive means the bytes are neither a zip nor a gzipped tar.

View Source
var ErrStreamEnded = errors.New("magpieplugin: the stream has ended")

ErrStreamEnded reports reading past the end of a stream.

View Source
var ErrTooManyModules = errors.New("magpieplugin: module graph exceeds limit")

ErrTooManyModules is reported when a package's graph exceeds MaxModules.

View Source
var NodeBuiltins = map[string]bool{
	"assert": true, "buffer": true, "child_process": true, "crypto": true,
	"dns": true, "events": true, "fs": true, "http": true, "http2": true,
	"https": true, "net": true, "os": true, "path": true, "process": true,
	"querystring": true, "stream": true, "string_decoder": true, "tls": true,
	"url": true, "util": true, "vm": true, "zlib": true,
}

NodeBuiltins are the Node specifiers a Magpie provider package may import. They are not implemented here: a report names them so a runtime can decide whether a declared host adapter covers the package, instead of hiding a missing capability behind a stub.

Functions

func ReadArchive

func ReadArchive(data []byte) (map[string][]byte, error)

ReadArchive turns a downloaded package into the flat file table NewBundle takes. A package is published either as a zip or as an npm tarball (tar.gz), and both usually carry a single top-level directory, which is stripped: the files are the same package either way, and the directory name is an accident of how it was packed.

Symlinks, device entries and absolute paths are refused rather than followed: an installer must not be able to write outside the package, and a link has no meaning once the files live in memory.

Types

type Attempt

type Attempt struct {
	// OutputStarted is set once any non-empty text or reasoning reached the
	// reader.
	OutputStarted bool
}

Attempt tracks one try at a reply. A client uses it to decide whether a failure may fall back to another account or provider.

func (*Attempt) MayRetry

func (a *Attempt) MayRetry() error

MayRetry says whether another attempt is allowed.

func (*Attempt) Saw

func (a *Attempt) Saw(event Event)

Saw records an event's effect on the attempt. A done event, an empty delta or a vendor error does not count as output: none of them showed the reader text.

type AuthStore

type AuthStore interface {
	// Get returns the stored sign-in for provider, or nil when there is none.
	Get(ctx context.Context, provider string) (map[string]any, error)
	// Set replaces the stored sign-in for provider.
	Set(ctx context.Context, provider string, value map[string]any) error
}

AuthStore is the client's sign-in storage for provider packages. Core never keeps credentials itself: the client writes them where it keeps secrets (Keychain on Apple), and hands them back by provider id.

type Bundle

type Bundle struct {
	// contains filtered or unexported fields
}

Bundle is an immutable snapshot of regular package files supplied by the client. Keys are package-relative slash paths, with no enclosing package/ directory. Archive extraction must reject symlinks and non-regular entries before passing files here. No filesystem paths are opened by this package.

func NewBundle

func NewBundle(files map[string][]byte) (*Bundle, error)

NewBundle checks a package against the limits and path rules, then keeps copies of its files. Nothing outside the package's own tree is reachable from the result.

func (*Bundle) Entries

func (b *Bundle) Entries() ([]string, error)

Entries mirrors Magpie's provider entry candidate order: ./server export, main, root export, then index files. It returns existing candidates in order; the future runtime must check exports and may fall back to the next entry. TypeScript candidates are retained; this package does not transpile them.

func (*Bundle) Manifest

func (b *Bundle) Manifest() Manifest

Manifest is the package's declaration, with its raw JSON copied so a caller cannot alter the bundle by editing what it was handed.

func (*Bundle) Read

func (b *Bundle) Read(name string) ([]byte, error)

Read returns a copy; plugin source and JSON number spelling stay untouched.

func (*Bundle) Resolve

func (b *Bundle) Resolve(from, spec string) (string, error)

Resolve locates an explicit relative module inside the snapshot. It does not parse imports, resolve npm dependencies, execute Node modules or access disk. Bare and node: specifiers are reported separately from invalid paths so the runtime can route them to a declared compatibility adapter in the future.

type ChatRequest

type ChatRequest struct {
	Model    string
	Messages []Message
	// System is separate because Anthropic Messages takes it out of band.
	System string
	// MaxTokens caps the reply; vendors disagree on whether it is required,
	// so zero leaves it out.
	MaxTokens int
	// Extra holds vendor parameters (temperature and the like) copied
	// verbatim into the body.
	Extra map[string]json.RawMessage
}

ChatRequest is one conversation turn to send.

func (*ChatRequest) Body

func (r *ChatRequest) Body(d Dialect) ([]byte, error)

Body encodes the request in a dialect's own shape.

type CheckinOutcome

type CheckinOutcome string

CheckinOutcome is what a check-in came to.

const (
	// CheckinClaimed means the check-in was pressed and succeeded now.
	CheckinClaimed CheckinOutcome = "claimed"
	// CheckinDone means it was already done today.
	CheckinDone CheckinOutcome = "done"
	// CheckinIneligible means the account cannot take part.
	CheckinIneligible CheckinOutcome = "ineligible"
	// CheckinInactive means the vendor runs no check-in right now.
	CheckinInactive CheckinOutcome = "inactive"
	// CheckinCaptcha means a captcha stands in the way. Magpie never solves one
	// and neither does this: the user checks in in the vendor's own app.
	CheckinCaptcha CheckinOutcome = "captcha"
	// CheckinFailed means it did not work.
	CheckinFailed CheckinOutcome = "failed"
)

type CheckinResult

type CheckinResult struct {
	Outcome CheckinOutcome `json:"outcome"`
	// Credit is what it gave, when it said.
	Credit string `json:"credit"`
	// Streak is consecutive days, when it said.
	Streak float64 `json:"streak"`
	// Message is the vendor's own words, kept for display.
	Message string `json:"message"`
	// Until is when the vendor's own day turns, as RFC 3339.
	Until string `json:"until"`
}

CheckinResult is one account's check-in answer.

type Decision

type Decision struct {
	Retry  bool
	Reason Reason
}

Decision is the answer to "may this attempt fall back to the next endpoint, and why".

func Decide

func Decide(err error, attempt *Attempt) Decision

Decide classifies a failed attempt.

The order matters. A cancelled request outranks a refused key, because there is no reader left to serve either way; text already shown outranks a 429, because falling back would repeat what was read. Only then is the status looked at, and only then does the question become "would another endpoint do better".

func (Decision) String

func (d Decision) String() string

type Dialect

type Dialect string

Dialect is the wire API a provider speaks.

const (
	DialectChat      Dialect = "chat"      // OpenAI Chat Completions
	DialectResponses Dialect = "responses" // OpenAI Responses
	DialectMessages  Dialect = "messages"  // Anthropic Messages
)

type Endpoint

type Endpoint struct {
	URL     string
	Header  map[string][]string
	Dialect Dialect
	// Name is what the client calls this endpoint in a message about it. It is
	// never sent.
	Name string
	// Account names the credential behind this endpoint. A retry may rotate it;
	// nothing else is sent, and it is only read when a pin is set.
	Account string
	// Model is what this endpoint was built to ask for. It is the label a
	// PinModel retry is allowed to keep.
	Model string
}

Endpoint is one place a conversation may go: a URL the client's transport can reach, the headers the account needs, and the wire dialect it speaks.

func (Endpoint) Label

func (e Endpoint) Label() string

Label names the endpoint in errors.

type Event

type Event struct {
	Kind EventKind
	// Text is this piece's text, or an error's message.
	Text string
	// Finish is why the message ended, in the vendor's own words: "stop",
	// "completed" and "end_turn" all mean the same thing.
	Finish string
	// Outcome is the same ending in this core's vocabulary, so a caller does not
	// carry one table per dialect.
	Outcome FinishReason
	// Usage is the token count the vendor reported, when it reported one.
	Usage *Usage
}

Event is one piece of a streamed reply.

type EventKind

type EventKind string

EventKind is what a streamed piece says.

const (
	// EventText is assistant text.
	EventText EventKind = "text"
	// EventReasoning is thinking the vendor streamed separately.
	EventReasoning EventKind = "reasoning"
	// EventDone ends the message; Text and Reason carry what is known.
	EventDone EventKind = "done"
	// EventError is a vendor error inside a successful response.
	EventError EventKind = "error"
)

type External

type External struct {
	Spec string
	Kind string
	// From lists the package files that import it, sorted.
	From []string
}

External is a specifier the package imports that is not a file in it.

type FinishReason

type FinishReason string

FinishReason is why a reply ended, in this core's vocabulary.

The three dialects spell the same endings differently: Chat says "stop", Responses says "completed", Anthropic says "end_turn"; the token limit is "length", "incomplete" and "max_tokens". A caller that wants to know whether a reply was cut short should not have to carry three tables, so the raw string is kept next to a normalised one.

const (
	// FinishStop means the model finished what it was saying.
	FinishStop FinishReason = "stop"
	// FinishLength means the token limit cut it short.
	FinishLength FinishReason = "length"
	// FinishToolCalls means it stopped to call a tool.
	FinishToolCalls FinishReason = "tool_calls"
	// FinishContentFilter means the vendor suppressed the rest.
	FinishContentFilter FinishReason = "content_filter"
	// FinishCancelled means the caller or the vendor cancelled the run.
	FinishCancelled FinishReason = "cancelled"
	// FinishError means the run failed.
	FinishError FinishReason = "error"
	// FinishInProgress means the vendor reported a state that is not an ending.
	FinishInProgress FinishReason = "in_progress"
)

func NormalizeFinish

func NormalizeFinish(dialect Dialect, raw string) FinishReason

NormalizeFinish turns one dialect's ending into this vocabulary.

An ending nobody has seen before becomes `FinishReason(raw)` rather than FinishStop: calling an unknown outcome "finished" is the one answer that is certainly wrong, and a new vendor word should read as itself in a log.

func (FinishReason) Truncated

func (r FinishReason) Truncated() bool

Truncated says whether the reply was cut short, which is the question most callers actually have.

type HeaderStreamer

type HeaderStreamer interface {
	Streamer
	DoStreamWithHead(ctx context.Context, req *Request, onHead func(*Response) error, onChunk func([]byte) error) (*Response, error)
}

HeaderStreamer adds early response metadata to Streamer. Call onHead once, before onChunk, as soon as headers arrive; call both callbacks sequentially. Without this optional interface fetch must wait for DoStream to return its response metadata. Existing Streamer implementations remain supported.

type Host

type Host interface {
	Do(ctx context.Context, req *Request) (*Response, error)
}

Host is what a client must provide for a package that uses the network. Do must honour ctx cancellation; a cancelled context should come back as an error, which rejects the package's fetch.

type Instance

type Instance struct {
	// contains filtered or unexported fields
}

Instance runs one account's copy of a package. Its own runtime means one plugin's globals, timers and errors never reach another's.

func (*Instance) Authorize

func (in *Instance) Authorize(methodIndex int, inputs map[string]any) (map[string]any, error)

Authorize starts one sign-in method and returns the page to show the user.

func (*Instance) Call

func (in *Instance) Call(export string, arg any) (any, error)

Call calls an exported function with one argument, converting Go values to JavaScript and the result back. Async results are awaited by the runtime. The argument is passed as the plugin's `input` object, which is how a Magpie plugin receives its client.

func (*Instance) CancelSignIn

func (in *Instance) CancelSignIn(id int64) error

CancelSignIn forgets a pending sign-in.

func (*Instance) Chat

func (in *Instance) Chat(ctx context.Context, req *ChatRequest, onEvent func(Event) error) error

func (*Instance) Checkin

func (in *Instance) Checkin(provider string) (*CheckinResult, error)

Checkin presses the account's check-in and normalises the answer.

func (*Instance) CheckinJSON

func (in *Instance) CheckinJSON(provider string) (string, error)

CheckinJSON is Checkin as JSON, for a client that speaks JSON.

func (*Instance) Close

func (in *Instance) Close()

Close ends the instance: running fetches are cancelled and the runtime is stopped. The instance must not be used afterwards.

func (*Instance) Exports

func (in *Instance) Exports(name string) bool

Exports asks whether the package exports name, without calling anything.

func (*Instance) InstallPluginBridge

func (in *Instance) InstallPluginBridge() error

InstallPluginBridge makes the package's plugin reachable as JSON hooks. It must run after the globals the package expects (fetch, client.auth) exist.

func (*Instance) Interrupt

func (in *Instance) Interrupt(reason any)

Interrupt stops running code: a package that loops forever must not hold the caller. The plugin stays unusable afterwards, so callers create a new instance for the next attempt.

func (*Instance) Models

func (in *Instance) Models(ctx context.Context) ([]Model, error)

Models asks the package's vendor what it serves.

func (*Instance) ModelsJSON

func (in *Instance) ModelsJSON(ctx context.Context) (string, error)

ModelsJSON is Models as JSON, for a client that speaks JSON.

func (*Instance) PluginAuth

func (in *Instance) PluginAuth() (map[string]any, error)

PluginAuth reports what the package's plugin offers: its provider id, its sign-in methods and its own options. A package without a plugin answers nil.

func (*Instance) Poll

func (in *Instance) Poll(id int64) (map[string]any, error)

Poll waits once for the user to finish signing in.

func (*Instance) SetFunction

func (in *Instance) SetFunction(name string, length int, fn moejs.NativeFunc) error

SetFunction defines a host function the package calls, such as `fetch`.

func (*Instance) SetGlobal

func (in *Instance) SetGlobal(name string, value any) error

SetGlobal defines a value the package reads, such as `console`.

func (*Instance) SetPluginOptions

func (in *Instance) SetPluginOptions(options map[string]bool)

SetPluginOptions hands the plugin its own switches: key "provider|option" to the value the user chose. Magpie keeps these per provider and lets the package read them through `input.magpie.option`.

func (*Instance) Usage

func (in *Instance) Usage(provider string) (map[string]any, error)

Usage runs the package's usage hook, when it has one.

func (*Instance) UsageJSON

func (in *Instance) UsageJSON(provider string) (string, error)

UsageJSON is UsageReport as JSON, for a client that speaks JSON.

func (*Instance) UsageReport

func (in *Instance) UsageReport(provider string) (*UsageReport, error)

UsageReport runs the package's usage hook and normalises its answer.

func (*Instance) UseClient

func (in *Instance) UseClient(provider string, store AuthStore) error

UseClient installs the sign-in bridge. A package may read the account it is running for and save a refreshed one; it cannot reach another provider's sign-in, because the id it names is checked against the instance's own.

func (*Instance) UseHost

func (in *Instance) UseHost(h Host) error

UseHost installs the network bridge and the Web APIs a package expects. Every fetch goes to h, which is the client's transport; nothing here opens a connection.

type Loader

type Loader struct {
	// contains filtered or unexported fields
}

Loader holds the compiled module graph of one package. It is immutable and safe to share: each account gets its own Instance.

func Load

func Load(b *Bundle) (*Loader, error)

Load compiles the package's entry and, through Link, every module it reaches. A module that is not in the snapshot, including a Node built-in or an npm package, is an error: nothing is resolved outside the package.

func (*Loader) NewInstance

func (l *Loader) NewInstance(opts Options) (*Instance, error)

NewInstance creates the runtime and evaluates the package's top level. Nothing network-bound happens here; the caller must first provide the globals the package expects, such as fetch and client.auth.

type Manifest

type Manifest struct {
	Name    string
	Version string
	Raw     json.RawMessage
}

Manifest keeps npm metadata and unrecognised fields in their original JSON form. Reading a manifest does not install dependencies or run scripts.

type Message

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message is one turn of a conversation. Roles are "user", "assistant" and "system"; a vendor that has no system turn gets its text folded into the first user message.

type Model

type Model struct {
	ID string `json:"id"`
	// Name is what to show; the vendor's own display name when it gave one.
	Name string `json:"name"`
	// Context and Output are token limits, 0 when the vendor did not say.
	Context int64 `json:"context"`
	Output  int64 `json:"output"`
	// Modalities lists what the model accepts, when the vendor said.
	Modalities []string `json:"modalities"`
	// Vendor is the raw object's owner field, kept for diagnostics.
	Vendor string `json:"vendor"`
}

Model is one model a client may choose.

type Options

type Options struct {
	// MemoryLimit is the JavaScript heap budget; zero means
	// DefaultMemoryLimit, negative means unlimited.
	MemoryLimit int64
	// DisableDynamicCode refuses eval and Function constructors, which a
	// provider package has no reason to need. Off by default because a
	// package that uses them would otherwise fail at an unpredictable
	// point; the report's caller decides.
	DisableDynamicCode bool
	// Locale is the Intl locale, "" for en-US.
	Locale string
}

Options configure one instance.

type Pin

type Pin string

Pin says how far a retry may move.

Choosing who answers and deciding whether a retry may pick someone else are two different decisions, and conflating them is how a conversation planned around one model quietly gets answered by another: the plan said "this is a hard question, use the strong model", the first account was busy, and the reply arrived from a small one.

A pin does not stop retries. It says which part of the route is allowed to change: the credential (an exhausted key), or nothing at all.

const (
	// PinAny lets a retry use any endpoint that is left. This is the default
	// because most callers pass a list that is already one route.
	PinAny Pin = ""
	// PinAccount keeps the endpoint's account and lets the address change.
	PinAccount Pin = "account"
	// PinModel keeps the model and lets the account change: a busy or rejected key
	// is exactly what a second account is for, and the model is what the reply was
	// planned around.
	PinModel Pin = "model"
)

type Reason

type Reason string

Reason names why a failed attempt may or may not be handed to the next endpoint.

It is part of the API rather than a log line on purpose: the question that otherwise costs an hour of reading logs is "why did this stop after the first endpoint when three were available", and a caller can now answer it from the returned error alone.

const (
	// ReasonCompleted means the attempt succeeded; nothing failed.
	ReasonCompleted Reason = "request_completed"
	// ReasonCancelled means the caller is gone. A cancelled request must not be
	// handed to another vendor: the person is no longer waiting for it, and
	// another attempt would spend someone else's quota answering nobody.
	ReasonCancelled Reason = "cancelled"
	// ReasonStoppedByCaller means the event callback asked the stream to end.
	ReasonStoppedByCaller Reason = "stopped_by_caller"
	// ReasonOutputStarted means the reader has already seen part of the reply.
	ReasonOutputStarted Reason = "output_already_shown"
	// ReasonRejected means the vendor refused the request itself. The same body
	// sent to the next endpoint is refused again, so trying is only slower.
	ReasonRejected Reason = "request_rejected"
	// ReasonCredential means the key or token was refused. Another account is
	// exactly what should be tried next.
	ReasonCredential Reason = "credential_rejected"
	// ReasonRateLimited means the account is out of quota or moving too fast.
	ReasonRateLimited Reason = "rate_limited"
	// ReasonUnavailable means the endpoint failed in a way that another one may
	// not: a 5xx, a timeout, or a transport error with no status at all.
	ReasonUnavailable Reason = "upstream_unavailable"
	// ReasonBudget means there was no endpoint left to try.
	ReasonBudget Reason = "no_endpoints_left"
	// ReasonPinned means the walk ended because a pin, not a failure, kept the
	// remaining endpoints out.
	ReasonPinned Reason = "pinned"
)

type Report

type Report struct {
	// Entry is the first existing entry candidate.
	Entry string
	// Modules are the package files reachable from Entry, sorted.
	Modules []string
	// Externals are what must be provided by the host or bundled, sorted by
	// specifier.
	Externals []External
	// Missing are specifiers that look like package files but are not in it.
	Missing []string
}

Report is what a package needs before its code can run. It is a static scan, not a proof of compatibility: a specifier reached only through computed code (eval, a dynamic template) is not seen, and loading a package still requires its hooks to run against a signed-in account.

func Analyze

func Analyze(b *Bundle) (Report, error)

Analyze walks the package from its first entry and reports what it needs outside itself. It opens no files: the snapshot is the only input.

func (Report) BareSpecifiers

func (r Report) BareSpecifiers() []string

BareSpecifiers lists npm dependencies the package imports, sorted.

func (Report) NodeSpecifiers

func (r Report) NodeSpecifiers() []string

NodeSpecifiers lists the Node built-ins the package needs, without the node: prefix, sorted.

type Request

type Request struct {
	Method string
	URL    string
	// Header maps canonical keys to values in the order given.
	Header map[string][]string
	Body   []byte
}

Request is one HTTP request a package asked for. The client sends it: Core opens no connections, and the package never sees the client's transport.

type ResetWindow

type ResetWindow struct {
	Until  string `json:"until"`
	Window string `json:"window"`
}

ResetWindow is one window's own reset.

type Response

type Response struct {
	Status     int
	StatusText string
	Header     map[string][]string
	Body       []byte
	URL        string
}

Response is what the client got back. A non-2xx status is not an error: packages inspect it themselves.

type RouteError

type RouteError struct {
	Tried []Endpoint
	Last  error
	// Stopped is the reason the walk ended before the endpoints ran out. Empty
	// or ReasonBudget means all of them were tried.
	Stopped Reason
	// Pin is the rule that kept other endpoints out, when one did.
	Pin Pin
}

RouteError reports why the walk over endpoints ended and what the last failure was.

func (*RouteError) Error

func (e *RouteError) Error() string

func (*RouteError) Unwrap

func (e *RouteError) Unwrap() error

type Sender

type Sender struct {
	// Host sends the requests. When it also implements Streamer, events arrive
	// as the vendor writes them; otherwise the whole reply is read at once.
	Host Host
	// MaxEventBytes caps one stream event; zero uses the decoder's default.
	MaxEventBytes int
	// Pin limits how far a failure may wander. Zero value is PinAny.
	Pin Pin
}

Sender sends conversations through the client's transport and reports the result as stream events.

func (*Sender) Send

func (s *Sender) Send(ctx context.Context, endpoints []Endpoint, req *ChatRequest, onEvent func(Event) error) (Endpoint, error)

Send tries the endpoints in order until one answers, and calls onEvent for each piece.

A failure before anything reached the reader moves to the next endpoint: a rejected key or a busy host is exactly what a second account is for. Once text or reasoning has been reported, a failure is returned with ErrNoRetryAfterOutput instead, because a second attempt would either repeat what the reader already read or contradict it.

type StatusError

type StatusError struct {
	Endpoint Endpoint
	Status   int
	Body     string
}

StatusError is an endpoint answering with a status that is not a success. The body is kept small: enough to recognise the vendor's complaint.

func (*StatusError) Error

func (e *StatusError) Error() string

type StreamReader

type StreamReader struct {
	// contains filtered or unexported fields
}

StreamReader turns one streamed reply into events. It reads the caller's reader through host/sse; it opens nothing.

func NewStreamReader

func NewStreamReader(r io.Reader, dialect Dialect, maxEventBytes int) (*StreamReader, error)

NewStreamReader reads dialect's events from r. maxEventBytes bounds one event block, as the client's own limit does.

func (*StreamReader) Next

func (s *StreamReader) Next() (Event, error)

Next returns the next event. A vendor's own end marker produces one EventDone and then io.EOF; an unreadable event is an error naming the dialect, never a silent skip.

type Streamer

type Streamer interface {
	// DoStream sends req and calls onChunk for each piece of the body. It
	// returns when the body ends, or with an error; a handler error stops it.
	DoStream(ctx context.Context, req *Request, onChunk func([]byte) error) (*Response, error)
}

Streamer is a Host that can also hand a reply over in chunks. A client that implements it lets a package read a streaming response as it arrives; one that does not still works, with replies that arrive whole.

type Usage

type Usage struct {
	Input      json.Number
	Output     json.Number
	CacheRead  json.Number
	CacheWrite json.Number
	Raw        json.RawMessage
}

Usage is a vendor's token accounting. Numbers are kept as json.Number so a large count is not rounded through a float.

type UsageReport

type UsageReport struct {
	Plan string `json:"plan"`
	// Until is the vendor's own day or window end, as RFC 3339, when it said.
	Until string `json:"until"`
	// Renew is "auto", "off", or empty when the vendor said neither.
	Renew   string `json:"renew"`
	Balance string `json:"balance"`
	Error   string `json:"error"`
	User    string `json:"user"`
	// SignIn is "expired", "kept", "renewed", or empty.
	SignIn string       `json:"signIn"`
	Resets *UsageResets `json:"resets"`
	// Windows are the quota windows the account has.
	Windows []UsageWindow `json:"windows"`
}

UsageReport is one account's usage, normalised.

func NormalizeUsage

func NormalizeUsage(raw map[string]any) UsageReport

NormalizeUsage turns whatever a package answered into the report a client can show.

type UsageResets

type UsageResets struct {
	Count    float64       `json:"count"`
	Until    string        `json:"until"`
	ByWindow bool          `json:"byWindow"`
	FiveHour float64       `json:"fiveHour"`
	Weekly   float64       `json:"weekly"`
	Team     bool          `json:"team"`
	Each     []ResetWindow `json:"each"`
}

UsageResets is when the vendor's windows turn over.

type UsageWindow

type UsageWindow struct {
	Name string `json:"name"`
	// Used may be past 100 when overspent, and is nil when unsaid.
	Used      *float64 `json:"used"`
	ResetsAt  string   `json:"resetsAt"`
	ResetSecs float64  `json:"resetSecs"`
	Display   string   `json:"display"`
	Amount    float64  `json:"amount"`
	Limit     float64  `json:"limit"`
	Unit      string   `json:"unit"`
	Span      float64  `json:"span"`
	Model     string   `json:"model"`
	Models    []string `json:"models"`
	NotModels []string `json:"notModels"`
	// Aside keeps a window out of routing: display only.
	Aside     bool    `json:"aside"`
	RunsOutAt string  `json:"runsOutAt"`
	RunsOut   float64 `json:"runsOut"`
	// Balance is a prepaid wallet's figure, nil when unsaid.
	Balance *float64 `json:"balance"`
}

UsageWindow is one quota. A nil field means the vendor did not say it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL