modelsource

package
v0.7.1 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package modelsource describes the places models come from without reading the machine or opening the network. Runtime facts are handed in by config.

Index

Constants

View Source
const ChatCompletionsPath = "/chat/" + "completions"

ChatCompletionsPath is composed so the repository's model-send-path law continues to reserve the literal endpoint for internal/provider. This package only describes the path; internal/config performs the probe.

View Source
const CodexName = "Codex"

CodexName is the Codex service's display name — its Source.Name, the one every surface calls it by. It is named once because it is ALSO the endpoint a Codex call row names (Source.ServedAs): the ChatGPT backend names no server of its own, and the row reads `"endpoint":"Codex"` the way an OpenRouter row reads the upstream that served it (#1391).

View Source
const CustomID = "custom"

CustomID is the identity of the vendored custom service row. The FIRST custom connection a profile persists keeps this id, so profiles and tests written before custom connections could multiply stay byte-identical; later instances mint CustomID-<slug> ids and are told apart by IsCustomID.

View Source
const DefaultID = "openrouter"

DefaultID is the stable identity of the service an unqualified model uses. It is named once because persisted rows, qualification, and every surface must agree on which member of a Set is the compatibility default.

View Source
const ProbeTimeout = 10 * time.Second

ProbeTimeout is the watching-person ceiling shared by every vendored probe.

Variables

This section is empty.

Functions

func AddressHost added in v0.3.0

func AddressHost(address string) string

AddressHost is the host a base URL is at, and the one step every caller takes before SourceSlug: the name a connection defaults to is the slug of its address's host. It lives beside SourceSlug because the two halves of that one rule were spelled three times — in the chat surface's draft, in config's mint, and inline in the surface's address step — and three copies of a defaulting rule drift into three different names for one host.

AN ADDRESS THE SURFACE ALREADY VALIDATED IS THE NORMAL CASE; an unparseable one, or one with no host at all, falls back to the raw trimmed text, which is what lets a bare host typed with no scheme still answer a usable name (url.Parse reads mybox.local:9001 as a scheme and an opaque path, and its Hostname is empty).

func Collides

func Collides(written string, taken []string, authors []string) (suggestion string, collides bool)

Collision says why a proposed Written may not be used, and what to use instead. Author segments arrive as an argument because this package may not reach internal/catalog.

func IDWord added in v0.3.0

func IDWord(written string) string

IDWord turns a written connection name into the plain word a minted custom id carries: lowercase, every run of characters outside a-z and 0-9 one dash, edge dashes trimmed, and connection when nothing remains. Routing keys on the written name, so this is persistence vocabulary only.

func IsCustomID added in v0.3.0

func IsCustomID(id string) bool

IsCustomID reports whether a persisted row id names a custom connection: the vendored row itself, or one of the instances minted after it. One predicate because every surface that used to compare against the literal must treat the instances as the same KIND of service, never as a second vendor. It is case-insensitive the way Set.ByID is, because both read ids a person's profile holds.

func LooksLikeAPIKey

func LooksLikeAPIKey(key string) bool

LooksLikeAPIKey is the shared OpenAI-shaped key rule. Config delegates its first-run check here so the DeepSeek row and the default service cannot drift.

func SourceSlug added in v0.3.0

func SourceSlug(host string) string

SourceSlug turns a base URL's host into the short word a person reads for the connection: api.deepseek.com answers deepseek, mybox.local answers mybox. It moved here from the chat surface so config and both surfaces derive one name from one host. AN ADDRESS THAT IS AN IP LITERAL IS TAKEN WHOLE: 127.0.0.1 answers 127-0-0-1, not the 0 the old derivation read off its last dot-separated label, and an IPv6 literal keeps its groups in order (::1 answers ipv6-1, fe80::1 answers fe80-1) — brackets are stripped defensively, a zone id is cut first (fe80::1%eth0 answers fe80-1, because the zone names the interface and not the host), :: and runs of mapped dashes collapse to one, and a colon-host that reduces to digits alone carries the ipv6- prefix so ::1 does not read as "1"; a hex group like fe80 keeps no prefix, because hex digits a-f are letters. A host that yields nothing answers CustomID, which is what the surface it moved from answered and keeps that path byte-identical.

func Split

func Split(model string, written []string) (segment, bare string)

Split applies the service-prefix grammar to an already level-less model id. A first segment that is not a connected Written remains part of the default service's model id.

Types

type Connected

type Connected struct {
	Source  Source
	Key     string
	Address string
	// Home is the profile directory whose rotating credentials belong to this
	// connection. Empty keeps the ordinary codeaf state root.
	Home string
	// Door is the bound billing road. It is zero for a one-door service, so all
	// older status and runtime behaviour remains byte-identical.
	Door Door
	// Overflow is the metered road a bound plan may use only when the person has
	// explicitly chosen it. Nil means there is no such road.
	Overflow   *Door
	PlanPaused string
}

Connected is one service with the two facts only a caller that may read the machine can fill in: the key that reaches it and the address it is at.

func (Connected) Qualify

func (c Connected) Qualify(bare string) string

Qualify spells a model the way a person selects it. Default-service and unnamed rows remain unqualified for compatibility.

type Door

type Door struct {
	ID      string
	Name    string
	Address string
	// Metered marks the road whose use can create a charge outside a fixed
	// plan. The fact lives on the door because an ID is persistence vocabulary,
	// not a billing policy for callers to reinterpret.
	Metered bool
	// KeyPrefix is a shortcut hint for ordering, never a claim. Every door is
	// still tried because a vendor may change its key convention.
	KeyPrefix string
	// Models is the catalog to trust when this door's own listing is wider than
	// the models the billing product actually serves. Empty believes the listing.
	Models []string
	// Observed says somebody has watched this door answer. It never gates use.
	Observed bool
}

Door is one way of paying for the same vendor's models: a base URL, and the word a person reads for it. ORDER IS THE POLICY — the subsidised door is first, because a person who has paid a subscription meant to use it.

type Listing

type Listing int

Listing is the vendored expectation for whether <base>/models exists on this service. It is a hint, never proof: connect always asks the service first, because silence in a documentation survey does not prove an endpoint absent.

const (
	// ListingNone is the first-try hint for a service no listing has been
	// observed on. It does NOT foreclose one: connect asks anyway, and a
	// service that answers is treated as a listing service from that moment.
	ListingNone Listing = iota
	// ListingModels is the first-try hint for a service whose model list is
	// documented or has been seen to answer.
	ListingModels
)

type Outcome

type Outcome struct {
	Kind       OutcomeKind
	VendorSaid string
	Models     int
	// ModelIDs are the non-empty ids carried by an answered listing. Keeping
	// them lets the surface retain the list it already paid for instead of
	// making a second catalog-shaped response the only road to the picker.
	ModelIDs []string
	Listed   bool
	// Refreshed distinguishes an answered live list from the vendored fallback.
	// It is meaningful only when Listed is true.
	Refreshed bool
	Door      Door
	// PlanPaused records that the selected door proved the plan exists but its
	// current usage window is spent. PlanReset is the vendor's readable reset
	// time when it supplied one, and Overflow is the separately billed road the
	// person may explicitly choose later.
	PlanPaused bool
	PlanReset  string
	Overflow   *Door
}

Outcome is what a connect attempt learned, in facts rather than a sentence: the surface owns the words and this package owns the truth.

type OutcomeKind

type OutcomeKind int

OutcomeKind distinguishes the facts learned by a connect attempt.

const (
	OutcomeConnected OutcomeKind = iota
	OutcomeRefused
	OutcomeAccountCannotPay
	OutcomeUnanswered
	OutcomeWrongShape
)

type Probe

type Probe struct {
	Address string
	Method  string
	Body    string
	Accepts []int
	Timeout time.Duration
}

Probe is the cheap read that proves a key works. It is a description only; internal/config performs the request beside the key it needs.

type Region

type Region struct {
	ID      string
	Name    string
	Address string
}

Region is one of a vendor's separate hosts, which are separate accounts with separate keys.

type Set

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

Set is the services this profile talks to, in the person's own order, the default service first and always present.

func NewSet

func NewSet(services ...Connected) Set

NewSet keeps services in the order given. The first service is the default.

func (Set) All

func (s Set) All() []Connected

All returns a copy in the person's order, with the default first.

func (Set) ByID

func (s Set) ByID(id string) (Connected, bool)

ByID finds a service by its stable persisted identity.

func (Set) Default

func (s Set) Default() Connected

Default returns the first service, or the zero value for an empty set.

func (Set) Empty

func (s Set) Empty() bool

Empty reports whether the set names no service at all.

func (Set) For

func (s Set) For(model string) (Connected, string)

For answers the service that serves model and the bare model id to send. Thinking levels are removed by internal/config before this pure package is called because internal/roles reaches process state through os.

func (Set) OrDefault

func (s Set) OrDefault(key, address string) Set

OrDefault makes a scalar account one default service. It preserves a set already supplied by a source-aware caller.

func (Set) WithDefaultKey

func (s Set) WithDefaultKey(key string) Set

WithDefaultKey returns the same ordered set with its default member's key replaced. It is the live first-run handoff: callers may update the account without constructing a Connected value and duplicating source resolution.

func (Set) Written

func (s Set) Written() []string

Written returns every segment a connected service claims.

type Source

type Source struct {
	ID      string
	Written string
	Name    string
	Address string
	Doors   []Door
	Regions []Region
	KeyEnv  string
	// KeyShape validates a supplied key. Nil accepts any non-blank value;
	// KeyOptional is the only way a service accepts blank.
	KeyShape func(string) bool
	// KeyOptional is true only when this service explicitly accepts no key.
	// It is a fact about the service, never inferred from a validation function.
	KeyOptional bool
	Probe       Probe
	Listing     Listing
	ProbeModel  string
	// A ROW'S PREFERRED MUST BE ANSWERABLE ON EVERY DOOR IT CAN BIND. The door
	// is chosen by what the key proves, so this is the vendor's best model both
	// its subscription and metered roads serve, not simply its flagship.
	Preferred string
	// ServedAs is the endpoint a transcript's call row names for this service's
	// answers when an answer names no machine of its own; empty for every
	// service that has not declared one, whose silent answers name nothing.
	//
	// IT IS ATTRIBUTION FOR THE RECORD AND NOTHING ELSE. A name that arrived on
	// an ANSWER is evidence internal/provider learns from — a lane to rate, a
	// machine to pin, a router account to clear — and it is drawn beside the
	// model on the live screen. A service whose backend IS its one machine has
	// no lane to learn and no second machine to draw, so its name is declared
	// here and written only into the call row (internal/session's
	// [Agent.attributedEndpoint]), never put on the answer (#1391).
	ServedAs string
}

Source is one place models come from: an address, a key description, and the facts about what lives there. IT IS CONFIGURATION AND NEVER A GUESS — nothing here reads a hostname to decide anything, because a router is recognised by what it answers.

func DefaultSource

func DefaultSource(address string) Source

DefaultSource is the synthesised OpenRouter row. The address is handed in because this package may not read the machine.

func Vendored

func Vendored() []Source

Vendored returns the service descriptions shipped by this phase.

func (Source) DoorProbe

func (s Source) DoorProbe() Probe

DoorProbe is the one-token request that proves which billing road this key can use. A multi-door row must name a current model rather than guess at the call site.

func (Source) FallbackProbe

func (s Source) FallbackProbe() Probe

FallbackProbe describes the one-token check used only after /models proves absent. An empty ProbeModel deliberately means believe the key until its first real call; guessing a current billable model is worse than deferring proof.

func (Source) MeteredDoor

func (s Source) MeteredDoor() (Door, bool)

MeteredDoor returns the one separately billed road described by this service. A missing answer means the service has no honest overflow road.

func (Source) OrderedDoors

func (s Source) OrderedDoors(key string) []Door

OrderedDoors returns every billing road exactly once. A matching prefix moves its likely door to the front and never removes any alternative.

func (Source) PreferredModel

func (s Source) PreferredModel(door Door, listed []string) string

PreferredModel answers the model a newly connected service should put the conversation on. THE ORDER IS THE POLICY: a door's documented catalog is narrower than the vendor row, then a row preference is trusted only when the service did not list models or listed that id, and only then may the first listed id stand in. Empty means there is no honest move to make.

Directories

Path Synopsis
Package sourcestub provides a small OpenAI-shaped service for source-routing tests.
Package sourcestub provides a small OpenAI-shaped service for source-routing tests.

Jump to

Keyboard shortcuts

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