oracle

package
v0.13.2 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package oracle is the model-tier routing of itd-2609170822093401: which tier of model each host-delegated agent deserves, how many agents a step may run at once, and, at run time, whether a configured provider takes the step or the harness does.

The table has one row per agent (a tier from a closed set, a fan-out bound, provider settings) and four layers, resolved through the shared layered configuration resolver (internal/core/layered): an invocation --route over the repository's .abcd/config/oracle-routing.json over the machine's ~/.abcd.noindex/oracle-routing.json over the bundled proposal. Nothing is applied until a table is accepted: with neither file present every agent resolves to the harness at host-decides, and the bundled proposal is what an accepted table falls back to for an agent it has no row for.

The resolver never writes, never reaches a network and never prints. It takes the machine's connections as a value (Connections), so a test hands it a provider that is "reachable" without a socket. The provider adapter (itd-2609081951381895, config.go) implements Connections from the machine's provider blocks, each connection carrying its allowlist, the settings its adapter accepts and the model each role pointed at it asks for; the delegating verbs hand every resolution the machine's connections, and a verb whose step resolves to a provider sends it there (spc-2609251028149555).

Staged, loudly (the loud-staging rule): spc-2609180535002478 lands the types, the proposal and its roster test, the store readers, the --route parser, Resolve, the bare board's oracle lines, the request block and receipt every delegating verb carries (Route.Request, Route.Receipt), and the ahoy consent step that writes an accepted table. spc-2609251028149555 adds the refusals Resolve makes on a provider leg before the step runs: a connection whose allowlist lists no model admits no route; the model the agent's oracle.roles.<agent> points at on the connection must be on its allowlist; a leg to a connection the agent's role does not point at names no model and is refused, naming the oracle.roles.<agent> setting to add; and a merged setting outside the set the connection's adapter accepts is refused, never dropped. It also adds the dispatch's core (dispatch.go): an agent whose role is pointed at a provider resolves to it with no --route (Connections.Pointed), APIConfig.Dispatch sends the step through it, and Route.FellBack leaves a step whose provider could not be reached to the harness. Escalating a tier after a failed fix round is still that spec's, and so is handing the dispatch to the delegating verbs: until they are wired every delegating verb resolves against NoConnections, so every step resolves to the harness and no front door reaches a provider-leg refusal.

Index

Constants

View Source 
const (
	// MaxProviders bounds the provider blocks one machine declares.
	MaxProviders = 16
	// MaxModels bounds one provider's allowlist.
	MaxModels = 64
	// MaxDenylist bounds the entries one layer adds to the denylist.
	MaxDenylist = 64
)

Bounds on what the configuration may carry.

View Source 
const (
	// KeyHomeExternal is a setup outside abcd (an environment variable or an
	// existing tool's configuration); abcd stores only where it is.
	KeyHomeExternal = credential.HomeExternal
	// KeyHomeABCD is abcd-only: the owner-only ~/.abcd.noindex/credentials.json.
	KeyHomeABCD = credential.HomeABCD
	// KeyHomeKeychain is the platform keychain.
	KeyHomeKeychain = credential.HomeKeychain
	// KeyHomeNone is a server that takes no key (a local one).
	KeyHomeNone = "none"
)

The homes a provider's key may live in (the intent's Decision 4): the credential store's three, and none.

View Source 
const (
	GuideQAddress = "address"
	GuideQLookup  = "lookup"
	GuideQModel   = "model"
	GuideQNarrow  = "model-narrow"
	GuideQTyped   = "model-name"
	GuideQTakes   = "takes-key"
	GuideQHome    = "home"
	GuideQEnv     = "env"
)

The ids of the guide's questions, as the resume object's answers name them.

View Source 
const (
	ListedListed   = "listed"    // the service listed its models, keyless
	ListedNeedsKey = "needs_key" // it lists them only for a key
	ListedNone     = "none"      // it gave no usable list; Reason says why
)

The look-up's outcomes, as the resume object carries them.

View Source 
const (
	// MaxSettingBytes bounds one setting's value, as JSON.
	MaxSettingBytes = 256
	// MaxSettings bounds how many settings one row or one --route carries.
	MaxSettings = 16
	// MaxRouteBytes bounds one --route's text, which a receipt carries verbatim.
	MaxRouteBytes = 1024
	// MaxModelBytes bounds the model a payload reports, in a receipt.
	MaxModelBytes = 200
)

Bounds on what a routing file or a --route may carry, enforced where the value is read (review-tier1 F6): everything that reaches a request block or a receipt has already passed them, so the receipt records settings as sent, whole, and never a truncation of them.

View Source 
const AdapterExplanation = "An aggregator (OpenRouter, for one) serves many vendors' models behind one " +
	"OpenAI-compatible address and one key, and a local OpenAI-compatible server is reached the same way. " +
	"abcd would use one for decision models and cheap judgements pointed at it by name, and only for the models its " +
	"list names: a model the person does not list, a frontier model included, is never asked for, " +
	"and the record shows what answered. " +
	"Everything works without one: with no provider configured, " +
	"every delegated step runs on the host."

AdapterExplanation is what the adapter is, what abcd would use it for and what works without it (criterion 6), in the words every surface uses: the ahoy gap, `abcd ahoy --providers` and the plugin page.

View Source 
const GuideSchemaVersion = 1

GuideSchemaVersion is the resume object's shape.

View Source 
const GuideStopped = "Nothing was set up; run the guide again to pick up where this left off."

GuideStopped is what a decide-later answer ends the guide with.

View Source 
const Harness = "harness"

Harness is the connection name of the harness leg: the host's own sub-agent dispatch, which owns model choice, credentials and execution (adr-25).

View Source 
const MaxCarriedBytes = 32 << 10

MaxCarriedBytes bounds the listed ids a resume object carries, as JSON: the first ids in the service's order that fit, and the count of the rest. A look-up keeps up to 5,000 ids, about 270 KB of JSON a turn: more than one argument may hold on linux (MAX_ARG_STRLEN, 128 KiB) when the host runs the page's command as sh -c, and more than a session should re-emit every turn. Real services list tens to a few hundred ids, which fit whole.

View Source 
const RouteSyntax = "<agent>=<tier>[@<connection>][?k=v,...]"

RouteSyntax is the --route flag's grammar, as every refusal names it.

Variables

View Source 
var KeyHomesProse = credential.HomesProse

KeyHomesProse is the prose above the choice of the key's home (criterion 8): the credential store's, which recommends the keychain in the prose and never as a marked option.

Functions

func Ceiling 

func Ceiling(agent string) (int, bool)

Ceiling returns the agent contract's fan-out ceiling; ok is false for a name outside the roster.

func CheckConnect added in v0.13.0 

func CheckConnect(req ConnectRequest) error

CheckConnect refuses, before the key is asked for, a request Connect would refuse on what needs no key: the provider's name, the base URL, the models named, the home and the key's name, the configuration in force, and a provider already configured there. A front door that reads the key from the person runs it first, so nobody pastes a key for a setup that cannot finish. The key itself, absent here, is Connect's to check.

func CredentialService added in v0.12.0 

func CredentialService(roots layered.Roots, name string) (credential.Service, bool, []string, error)

CredentialService is the walkthrough's service for the credential name, when a configured provider names it as its key: the walkthrough then verifies a key with that provider's own call. A name no provider names is not the adapter's. The configuration read's diagnostics come back beside it, for the front door to print on stderr, whether or not a provider names the name.

func KeyHomes added in v0.11.1 

func KeyHomes() []string

KeyHomes returns the homes in the order the setup offers them.

func ModelReported 

func ModelReported(payload []byte) string

ModelReported returns the model a payload names: its top-level "model" string, else a reading's "instrument.model". A payload that names none, or is not a JSON object, reports "". The value is untrusted, so it is bounded to MaxModelBytes and its hidden runes are percent-encoded: recorded, never able to reorder or escape the receipt it lands in.

func RenderRequestSection 

func RenderRequestSection(rr RequestRouting) string

RenderRequestSection renders the routing section a request document carries, as indented key: value lines under "routing:". Every value is sanitised: the document is read by the host, and a value a file or a flag supplied must not carry a terminal escape or a reordering rune into it.

func Roster 

func Roster() []string

Roster returns every agent the proposal names, sorted: the runtime roster a table's rows are checked against.

func SelfContained added in v0.12.0 

func SelfContained() []string

SelfContained returns a copy of the self-contained list.

Types

type APIConfig added in v0.11.1 

type APIConfig struct {

	// Diagnostics are the non-fatal reports the read produced, one line each,
	// for a front door to print on stderr: a route naming a provider this
	// machine has not configured, a role outside the roster, and a skipped
	// repository route (one to a provider that holds a key, one whose name or
	// value is malformed, one to a model a keyless provider does not list, and
	// one to an unconfigured provider where the machine routes the name).
	Diagnostics []string
	// contains filtered or unexported fields
}

APIConfig is the adapter configuration one invocation read.

func LoadAPI added in v0.11.1 

func LoadAPI(r layered.Roots) (*APIConfig, error)

LoadAPI reads the provider configuration through the layered resolver and validates all of it. A fault is an error naming the file and the key; none falls through to a default.

func (*APIConfig) Admit added in v0.11.1 

func (c *APIConfig) Admit(provider, model string) error

Admit is the refusal adr-2609221009491186 names: it returns nil only when provider is configured, model is on its list, and no oracle.denylist entry the configuration wrote matches the model. It is consulted when the configuration is read and again by any dispatch, so a route never reaches a provider on a stale answer.

func (*APIConfig) Admitted added in v0.12.0 

func (c *APIConfig) Admitted(r Route) (Target, error)

Admitted returns the target r's step would be sent to, or the refusal Dispatch would make before any call: r is on the harness, this machine does not point oracle.roles.<agent> at r's connection, a provider that holds a key is reached through a route not set on this machine, or the agent is one ruling DR5 keeps off that provider (admitAgent). A front door calls it before it writes anything, so a step that will be refused writes nothing.

func (*APIConfig) BundledContextProviders added in v0.12.0 

func (c *APIConfig) BundledContextProviders() []string

BundledContextProviders returns the providers the override names, sorted.

func (*APIConfig) Call added in v0.11.1 

func (c *APIConfig) Call(ctx context.Context, creds credential.Source, req CallRequest, opts ...openaiapi.Option) ([]byte, CallRecord, error)

Call sends req through its target's provider and returns the answer the contract admitted and the call's record. It refuses before any call a target the configuration does not admit (Admit, again, so a target built anywhere but the read is held to the same rule) and a named key that resolves to nothing, because an unauthenticated call is never made. An answer whose reported model an oracle.denylist entry refuses is discarded: the provider substituted a model the configuration refuses, and the refusal names what it reported.

func (*APIConfig) Connections added in v0.11.1 

func (c *APIConfig) Connections() Connections

Connections returns the machine's provider connections, the implementation of Connections this configuration backs. A provider claims no tier: it is reached by a role or a judgement type pointed at it, or by a --route naming it, never by a tier alone, so Serves answers false for every tier and the tier-only steps stay on the harness. Pointed returns the connection an agent's role points at. Named returns the provider's connection carrying its allowlist, the settings the adapter accepts, and the model each role pointed at it asks for.

func (*APIConfig) Denylist added in v0.11.1 

func (c *APIConfig) Denylist() []DenyEntry

Denylist returns the denylist in force, the entries oracle.denylist holds, lowest layer first; empty when none is written, since abcd bundles none.

func (*APIConfig) Dispatch added in v0.12.0 

func (c *APIConfig) Dispatch(ctx context.Context, creds credential.Source, r Route, brief openaiapi.Brief,
	contract func([]byte) error, opts ...openaiapi.Option) ([]byte, ReceiptRoute, error)

Dispatch sends one step through r's provider connection and returns the payload the contract admitted and the receipt's route block, which names the provider as tried and used and carries the call's record.

Everything that decides where the step goes and with which key is taken again from this configuration, never from r alone: the model is the one oracle.roles.<agent> points at on r's connection, and a provider that holds a key is reached only through a route set on this machine, so only a route the person set up on their own machine spends their key (ruling AA(b) of 2026-09-29, itd-2609081951381895 Decision 8). A provider that holds a key takes only a self-contained agent, or one the person's override admits (ruling DR5 of 2026-09-29, admitAgent). Call then admits the target against the allowlist and oracle.denylist again and resolves the key by name. Every refusal is made before the provider is contacted and names the setting to change. An error that is openaiapi.ErrUnreachable means nothing was sent, and FellBack gives the route that leaves the step to the harness.

func (*APIConfig) Judgement added in v0.11.1 

func (c *APIConfig) Judgement(kind string) (Target, bool)

Judgement returns where a judgement type is pointed, if it is.

func (*APIConfig) Provider added in v0.11.1 

func (c *APIConfig) Provider(name string) (Provider, bool)

Provider returns one configured provider.

func (*APIConfig) Providers added in v0.11.1 

func (c *APIConfig) Providers() []Provider

Providers returns the configured providers, sorted by name.

func (*APIConfig) Role added in v0.11.1 

func (c *APIConfig) Role(agent string) (Target, bool)

Role returns where an agent is pointed, if it is.

func (*APIConfig) Routes added in v0.11.1 

func (c *APIConfig) Routes() []PointedRoute

Routes returns every role and judgement type pointed at a provider, roles first, each family sorted by name.

type BoardLayer 

type BoardLayer struct {
	Layer  string `json:"layer"`
	Origin string `json:"origin"`
	Tier   Tier   `json:"tier"`
	FanOut int    `json:"fan_out"`
}

BoardLayer is one layer's row for an agent, as the bare board shows it.

type BoardRow 

type BoardRow struct {
	Agent  string       `json:"agent"`
	Winner string       `json:"winner"`
	Layers []BoardLayer `json:"layers"`
}

BoardRow is one agent's routing on the bare board: every layer holding a row, highest precedence first, and the layer whose row applies.

type CallRecord added in v0.11.1 

type CallRecord struct {
	Provider      string `json:"provider"`
	ModelAsked    string `json:"model_asked"`
	ModelReported string `json:"model_reported"`
	// Credential is the name of the credential the call used, never its
	// value; empty for a provider that takes no key (itd-2609221017023290
	// criterion 5).
	Credential string `json:"credential,omitempty"`
}

CallRecord is the per-call record the run record carries (criterion 5, adr-2609221009491186 Decision 5): the provider, the model asked for and the model the provider reported, side by side, so a substitution is visible, and the name of the credential the call used. It never carries a key or the brief.

type CallRequest added in v0.11.1 

type CallRequest struct {
	Target   Target
	Brief    openaiapi.Brief
	Settings Settings
	// Contract is the output contract the host sub-agent's payload is judged
	// by; nil admits any answer.
	Contract func([]byte) error
}

CallRequest is one call: where it goes, the brief, the settings as sent and the output contract the answer is judged by.

type ConnectRequest added in v0.11.1 

type ConnectRequest struct {
	// Roots are where the configuration in force is read: the oracle.denylist
	// a model is held to, and the provider blocks a name must not repeat. The
	// writes land under Roots.Home alone.
	Roots    layered.Roots
	Provider string
	BaseURL  string
	// Models is the first allowlist; the verification call asks for the first.
	Models []string
	// Home is where the key lives: one of KeyHomes.
	Home string
	// KeyName is the credential's name; "" names it after the provider.
	KeyName string
	// Key is the value, for the abcd and keychain homes. It is never echoed.
	Key string
	// Pointer is where the key is, for the external home.
	Pointer credential.Pointer
	// Timeout bounds the verification call; 0 keeps its own short bound.
	Timeout time.Duration
	// Pick, when Models is empty, chooses one model from the listed ids.
	// Connect calls it after listing with the key it holds; nil refuses as today.
	Pick func(ctx context.Context, listed []string) (string, error)
}

ConnectRequest is one provider's setup.

type ConnectResult added in v0.11.1 

type ConnectResult struct {
	Provider string   `json:"provider"`
	BaseURL  string   `json:"base_url"`
	Models   []string `json:"models"`
	KeyHome  string   `json:"key_home"`
	KeyName  string   `json:"key_name,omitempty"`
	// Verified is the verification call's record.
	Verified CallRecord `json:"verified"`
	// Wrote names each file written, in the tilde form.
	Wrote []string `json:"wrote"`
	// Diagnostics are the configuration read's non-fatal reports (APIConfig's),
	// for the front door to print on stderr; the JSON form omits them, so they
	// are said once and never mixed into what a machine reader parses.
	Diagnostics []string `json:"-"`
}

ConnectResult is what the setup did. It never carries the key.

func Connect added in v0.11.1 

func Connect(ctx context.Context, req ConnectRequest) (ConnectResult, error)

Connect verifies the connection with one call and, only when it succeeds, writes the key and the provider block. Every fault the configuration read would refuse is refused first, before the call.

With no model named and Pick given, Connect first lists the service's models with the key it holds (pickModel), and the model picked is the allowlist; from there the path is the same. No listing is taken as the verification (itd-2610030821294016 decision 2): the completion to the model picked is.

type Connection 

type Connection struct {
	Name     string
	Defaults Settings
	// Models is the provider's allowlist (adr-2609221009491186): the only
	// models it may serve, every one already cleared against oracle.denylist
	// when the configuration was read. nil on a connection no
	// provider block backs.
	Models []string
	// Accepts is the settings the connection's adapter accepts; a setting
	// outside it is refused before a step runs, never dropped
	// (spc-2609251028149555, AC 8). nil on a connection no adapter backs.
	Accepts []string
	// Roles is the model each agent whose oracle.roles.<agent> points at this
	// connection asks it for, keyed by agent: a provider is reached by a role
	// pointed at <provider>/<model> (itd-2609081951381895 Decision 9), so the
	// role is where a provider leg's model is chosen. nil when no role points
	// here.
	Roles map[string]string
	// Keyed reports that the provider holds a key: its block names a
	// credential, so a call through it spends the person's key. A keyed leg
	// takes no setting from the repository's routing row: only the person's
	// own machine configuration shapes a call that spends their key.
	Keyed bool
}

Connection is one provider connection configured on this machine, with the sampling settings it sends by default.

func (Connection) Accepted added in v0.11.1 

func (c Connection) Accepted(key string) bool

Accepted reports whether the connection's adapter accepts setting key.

func (Connection) Admits added in v0.11.1 

func (c Connection) Admits(model string) bool

Admits reports whether model is on the connection's allowlist.

type Connections 

type Connections interface {
	// Serves returns a configured connection that is reachable and can serve
	// the tier, if there is one.
	Serves(t Tier) (Connection, bool)
	// Named returns the configured connection of that name, if there is one.
	Named(name string) (Connection, bool)
	// Pointed returns the connection agent's role is pointed at, if it is.
	Pointed(agent string) (Connection, bool)
}

Connections is the machine's configured provider connections. The provider adapter intent (itd-2609081951381895) implements it; this package only consumes it, so it never configures, probes or reaches a provider itself.

type DenyEntry added in v0.11.1 

type DenyEntry struct {
	Pattern string `json:"pattern"`
	Origin  string `json:"origin"`
}

DenyEntry is one denylist entry and the layer that added it.

func Denied added in v0.11.1 

func Denied(denylist []DenyEntry, model string) (DenyEntry, bool)

Denied reports the first denylist entry that matches model. Matching ignores case, OpenRouter's ~ alias prefix, and for an exact entry a :variant suffix, so a spelling cannot slip a denied model past its entry.

type FlagRoute 

type FlagRoute struct {
	Agent      string
	Row        Row
	Connection string
	Text       string
}

FlagRoute is one parsed --route: a row for one agent for this invocation alone, the connection it names (if any), and the flag text verbatim.

func ParseRoutes 

func ParseRoutes(texts, dispatched []string, conns Connections) ([]FlagRoute, error)

ParseRoutes parses every --route value and refuses, before any step runs, a value that is malformed, names an agent this invocation does not dispatch (one outside the roster included), names a tier outside the vocabulary, names a connection not configured on this machine, carries a malformed setting, or repeats an agent. dispatched is the set of agents this invocation dispatches, which for every delegating verb is one agent, so a second --route naming another agent is refused rather than merged (the 2026-09-25 ruling on AC 7 in .abcd/work/DECISIONS.md).

type GuideAnswer added in v0.13.0 

type GuideAnswer struct {
	ID    string `json:"id"`
	Value string `json:"value"`
}

GuideAnswer is one answer the person gave: the question's id and the value recorded for it.

type GuideDone added in v0.13.0 

type GuideDone struct {
	Command  string   `json:"command"`
	Writes   []string `json:"writes"`
	Provider string   `json:"provider"`
	Home     string   `json:"home"`
	// PicksInTerminal is a command with no --model: the service lists its
	// models only for a key, so the command lists them in the terminal once it
	// holds the key, and the person picks there (decision 2).
	PicksInTerminal bool `json:"picks_in_terminal"`
}

GuideDone is the guide's end: the one command and every path it writes, in the tilde form and in the order a run reports them (G4).

type GuideListed added in v0.13.0 

type GuideListed struct {
	Status string   `json:"status"`
	Host   string   `json:"host"`
	Models []string `json:"models,omitempty"`
	// More is how many of the ids listed are not carried (MaxCarriedBytes).
	More   int    `json:"more,omitempty"`
	Reason string `json:"reason,omitempty"`
}

GuideListed is what the one look-up found.

type GuideRefusal added in v0.13.0 

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

GuideRefusal is a turn the guide refuses: a resume object or an answer it cannot admit. Nothing was asked of the service and nothing written.

func (*GuideRefusal) Error added in v0.13.0 

func (e *GuideRefusal) Error() string

type GuideRequest added in v0.13.0 

type GuideRequest struct {
	// Roots are where the configuration in force is read: the provider names
	// already taken, the denylist, and the models the person already uses.
	Roots layered.Roots
	// Provider and BaseURL are what the first turn was given; a resumed turn
	// takes them from Resume.
	Provider string
	BaseURL  string
	// Resume is the previous turn's resume object; nil starts the guide.
	Resume *GuideState
	// Answer is the answer to Resume.Open; nil asks the open question again.
	Answer *string
	// EnvNames are the names of the variables in the guide's environment,
	// never their values: the external home's question offers the ones that
	// end in _API_KEY.
	EnvNames []string
}

GuideRequest is one turn's input.

type GuideState added in v0.13.0 

type GuideState struct {
	SchemaVersion int           `json:"schema_version"`
	Provider      string        `json:"provider,omitempty"`
	BaseURL       string        `json:"base_url,omitempty"`
	Answers       []GuideAnswer `json:"answers"`
	Listed        *GuideListed  `json:"listed,omitempty"`
	// Open is the question the next answer is for.
	Open string `json:"open,omitempty"`
}

GuideState is the resume object: everything the next turn needs, written out on stdout and passed back on stdin. It never carries a key.

type GuideTurn added in v0.13.0 

type GuideTurn struct {
	Ask     *question.Ask `json:"ask,omitempty"`
	Done    *GuideDone    `json:"done,omitempty"`
	Stopped string        `json:"stopped,omitempty"`
	Resume  GuideState    `json:"resume"`
}

GuideTurn is one turn: a question to ask, the end, or a stop (decide later), and the resume object for the next turn.

func Guide added in v0.13.0 

func Guide(ctx context.Context, req GuideRequest) (GuideTurn, error)

Guide returns the next turn of the guided setup. It writes nothing and reads no key home; its one request is the keyless look-up of the service's models, made only on the person's yes and only once.

type LayerRow 

type LayerRow struct {
	Layer  layered.Layer
	Origin string
	Row    Row
	// Connection is the connection a --route named (flag layer only).
	Connection string
}

LayerRow is one layer's row for an agent, as a board renders it.

type Layered 

type Layered struct {

	// Diagnostics are the non-fatal reports a read produced, one line each,
	// for the front door to print on stderr before any step runs: an orphan
	// row (named, skipped, the rest apply) and a fan-out clamped to the
	// contract ceiling.
	Diagnostics []string
	// contains filtered or unexported fields
}

Layered is the routing table's four layers for one invocation.

func Load 

func Load(r layered.Roots) (*Layered, error)

Load reads the repository and machine routing files through the layered resolver and validates every row in them. A malformed file or row is an error naming the file; an orphan row and a clamped fan-out are Diagnostics.

func (*Layered) Accepted 

func (l *Layered) Accepted() bool

Accepted reports whether a routing table exists at the repository or the machine layer, the condition under which any row applies.

func (*Layered) Apply 

func (l *Layered) Apply(routes []FlagRoute) error

Apply places parsed routes in the flag layer, where they win over every accepted table for this invocation.

func (*Layered) Board 

func (l *Layered) Board() ([]BoardRow, error)

Board returns one row per agent in the roster, or nil when nothing is accepted (the board is then unchanged: every step runs through the harness at host-decides, which is what the board already implies). The winner is Resolve's own Source, so the board and a step can never disagree.

func (*Layered) Rows 

func (l *Layered) Rows(agent string) ([]LayerRow, error)

Rows returns every layer's row for agent, highest precedence first, with the bundled proposal last. Whether the bundled row applies is Resolve's answer (it does only once a table is accepted); Rows lists it regardless, so the board can show what an acceptance would change.

type NoConnections 

type NoConnections struct{}

NoConnections is a machine with no provider configured, and the only implementation until the adapter intent lands: every step goes to the harness, whatever its row says.

func (NoConnections) Named 

func (NoConnections) Named(string) (Connection, bool)

Named reports that no connection of any name is configured.

func (NoConnections) Pointed added in v0.12.0 

func (NoConnections) Pointed(string) (Connection, bool)

Pointed reports that no role is pointed at any connection.

func (NoConnections) Serves 

func (NoConnections) Serves(Tier) (Connection, bool)

Serves reports that nothing serves any tier.

type PointedRoute added in v0.11.1 

type PointedRoute struct {
	Kind   string `json:"kind"`
	Name   string `json:"name"`
	Target Target `json:"target"`
}

PointedRoute is one role or judgement type and its target, for a board.

type Provider added in v0.11.1 

type Provider struct {
	Name    string   `json:"name"`
	BaseURL string   `json:"base_url"`
	Key     string   `json:"key,omitempty"`
	Models  []string `json:"models"`
	Origin  string   `json:"origin"`
}

Provider is one configured provider block.

type ReceiptRoute 

type ReceiptRoute struct {
	Agent           string   `json:"agent"`
	TierAsked       Tier     `json:"tier_asked"`
	ConnectionTried string   `json:"connection_tried"`
	ConnectionUsed  string   `json:"connection_used"`
	FallbackReason  string   `json:"fallback_reason"`
	Override        string   `json:"override"`
	SettingsSent    Settings `json:"settings_sent"`
	// ModelReported is the payload's own model field, "" when it names none
	// (requiring it is itd-2609180517121254's).
	ModelReported string `json:"model_reported"`
	// ProviderCall is the call through a provider adapter that produced the
	// payload: the provider, the model asked for and the model the provider
	// reported (itd-2609081951381895 criterion 5). null on the harness leg.
	ProviderCall *CallRecord `json:"provider_call"`
}

ReceiptRoute is the receipt's route block (AC 4, 5, 7, 8): what was asked, which connection was tried and which used, why a step fell back, the override verbatim, the settings as sent, and the model the payload reported, side by side. Every field is always present, so a reader tells "none" from "not recorded".

func (ReceiptRoute) WithCall added in v0.11.1 

func (rr ReceiptRoute) WithCall(c CallRecord) ReceiptRoute

WithCall returns the receipt carrying the provider call that produced its payload.

type RequestRouting 

type RequestRouting struct {
	Agent  string `json:"agent"`
	Tier   Tier   `json:"tier"`
	FanOut int    `json:"fan_out"`
	// Source is the deciding layer: flag, repo, machine, bundled, or none.
	Source string `json:"source"`
	// Origin names that layer's file, the flag text, "bundled" or "none".
	Origin string `json:"origin"`
	// Override is the --route text verbatim when one governed the step.
	Override string `json:"override,omitempty"`
	// Connection is the leg: a provider connection's name, or harness.
	Connection string `json:"connection"`
	// Fallback is why a tier that asked for a provider went to the harness.
	Fallback string `json:"fallback,omitempty"`
}

RequestRouting is the request block's routing section for the one agent a step dispatches: the tier and fan-out bound the host is asked to honour, the layer that decided them, and the leg the step goes to (AC 1, AC 4).

type Route 

type Route struct {
	Agent string
	// Row is the winning row, the flag's overrides applied and the fan-out
	// clamped to the contract ceiling.
	Row Row
	// Source is the layer the row came from: flag, repo, machine, bundled, or
	// none when nothing is accepted.
	Source layered.Layer
	// Origin names that layer's file, the flag text, "bundled" or "none".
	Origin string
	// Override is the --route text verbatim when a flag governed the step, so
	// a measurement run is never mistaken for accepted routing.
	Override string
	// ConnectionTried is the provider connection the step was offered to; ""
	// when none was (host-decides, or no connection serves the tier).
	ConnectionTried string
	// ConnectionUsed is the provider connection that takes the step, or
	// Harness.
	ConnectionUsed string
	// Fallback is why a step whose tier asked for a provider went to the
	// harness; "" when it did not fall back. The front door prints it on
	// stderr before the step runs.
	Fallback string
	// SettingsSent is the provider leg's settings: the connection's defaults,
	// then the row's, then the flag's. nil on the harness leg.
	SettingsSent Settings
}

Route is one agent's resolved routing for one step: what the request block carries and what the receipt records.

func Resolve 

func Resolve(agent string, l *Layered, conns Connections) (Route, error)

Resolve returns agent's route: the flag's row over the repository's over the machine's over the bundled proposal (the last only once a table is accepted), resolved against conns. The leg is the connection a --route names; else, with no --route, the connection agent's role is pointed at; else the harness for host-decides, and a connection serving the tier for any other. It contacts no provider: Pointed is a lookup in the machine's own configuration, and conns is asked to serve only a tier that asks for a provider or a connection a --route named.

func (Route) FellBack added in v0.12.0 

func (r Route) FellBack(err error) (Route, bool)

FellBack returns r moved to the harness when err says its provider could not be reached (openaiapi.ErrUnreachable: nothing was sent), and false for any other error, which refuses the step instead. The step then runs through the harness with its tier named in the request, the receipt records the connection tried and the harness used, and Fallback is the one line the front door prints on stderr before the step runs (itd-2609170822093401, the fourth criterion, at dispatch).

func (Route) OnProvider added in v0.12.0 

func (r Route) OnProvider() bool

OnProvider reports whether r's step goes to a provider connection rather than the harness.

func (Route) Receipt 

func (r Route) Receipt(model string) ReceiptRoute

Receipt returns the route's receipt block, with the model the payload reported (ModelReported's answer).

func (Route) Request 

func (r Route) Request() RequestRouting

Request returns the route's request-block section.

type Row 

type Row struct {
	Tier Tier `json:"tier"`
	// FanOut is the most agents one step may run at once, itself included. It
	// may tighten the agent contract's ceiling and never raise it; 0 in a file
	// means "not stated", which resolves to the ceiling.
	FanOut   int      `json:"fan_out,omitempty"`
	Settings Settings `json:"settings,omitempty"`
}

Row is one agent's routing row.

type Settings 

type Settings map[string]json.RawMessage

Settings are provider sampling settings (temperature, seed, and whatever else a provider accepts), each a JSON scalar kept as its raw bytes so a number reaches the provider and the receipt exactly as written. Which keys a provider accepts is its adapter's judgement (itd-2609081951381895), never this package's: a key is shape-checked here and passed through.

type Table 

type Table map[string]Row

Table maps an agent's name to its row.

func Proposal 

func Proposal() Table

Proposal returns the bundled table: one row per agent, its tier and its fan-out at the contract ceiling. The map is a copy.

type Target added in v0.11.1 

type Target struct {
	Provider string `json:"provider"`
	Model    string `json:"model"`
	// Origin names the file the route came from.
	Origin string `json:"origin"`
}

Target is where a role or a judgement type is pointed: a configured provider and a model on its list.

func (Target) String added in v0.11.1 

func (t Target) String() string

String is the route as the configuration spells it.

type Tier 

type Tier string

Tier is a model tier: a class of model that survives model churn, not a model name. 

const (
	// Local: a model on this machine, for material that must not leave it.
	Local Tier = "local"
	// Economy: a cheap cloud model, for plumbing no human reads as a verdict.
	Economy Tier = "economy"
	// Frontier: the strongest model, for verdicts a human reads and acts on.
	Frontier Tier = "frontier"
	// HostDecides: no tier asked; the harness picks. The floor every step
	// stands on when nothing is accepted.
	HostDecides Tier = "host-decides"
)

func ParseTier 

func ParseTier(s string) (Tier, error)

ParseTier admits exactly a member of the vocabulary, spelled as it is.

func Tiers 

func Tiers() []Tier

Tiers returns the closed tier vocabulary.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.