runtime

package
v0.1.3 Latest Latest
Warning

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

Go to latest
Published: Jul 4, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package runtime is the **recommended entry point** for host applications (e.g. hawk). Start by calling runtime.Load to get a *Runtime, then rt.ChatProvider to obtain a client.Provider that you can hand to your agent loop.

Note: the "stable" surface of eyrie is actually a set of cooperating subpackages, not just this one. The full list hawk (and other host applications) actually import is:

github.com/GrayCodeAI/eyrie/runtime          (this package — bootstrap facade)
github.com/GrayCodeAI/eyrie/client           (Provider interface, message/response types)
github.com/GrayCodeAI/eyrie/catalog         (model catalog: pricing, capabilities, registry)
github.com/GrayCodeAI/eyrie/catalog/registry (ProviderSpec catalog: 16 registered providers)
github.com/GrayCodeAI/eyrie/catalog/xiaomi  (Xiaomi-specific catalog helpers)
github.com/GrayCodeAI/eyrie/config          (provider config + env var resolution)
github.com/GrayCodeAI/eyrie/credentials     (OS keyring + OIDC keyless CI auth)
github.com/GrayCodeAI/eyrie/setup           (CLI/setup wiring, RoutingPreviewJSON)
github.com/GrayCodeAI/eyrie/storage         (conversation DAG persistence)

They are all considered part of the public API; changes to exported names are gated by semver. Anything under internal/ is implementation detail and may change without notice.

Index

Constants

View Source
const (
	GatewayXiaomiTokenPlan = "xiaomi_mimo_token_plan"
)

Variables

This section is empty.

Functions

func ActiveGateway added in v0.1.3

func ActiveGateway(ctx context.Context) string

ActiveGateway returns the selected setup gateway derived from active provider/model state.

func ActiveModel

func ActiveModel(ctx context.Context) string

ActiveModel returns the selected model from provider.json.

func ActiveProvider

func ActiveProvider(ctx context.Context) string

ActiveProvider returns the selected provider from provider.json.

func ActiveProviderID added in v0.1.3

func ActiveProviderID(provider string) string

ActiveProviderID canonicalizes a host-facing provider/gateway id through the runtime provider-id rules used by Eyrie.

func AllModelIDs

func AllModelIDs(ctx context.Context) ([]string, error)

AllModelIDs returns every canonical model ID in the catalog (sorted).

func ApplyCredentialsForProvider added in v0.1.3

func ApplyCredentialsForProvider(ctx context.Context, providerID string) (*setup.ApplyCredentialsResult, error)

ApplyCredentialsForProvider refreshes runtime catalog/provider state for one gateway after saving credentials.

func ApplyGatewayEnv added in v0.1.3

func ApplyGatewayEnv(ctx context.Context, providerID string)

ApplyGatewayEnv applies derived env settings from provider.json for gateways that need them.

func AvailableProviders added in v0.1.3

func AvailableProviders() []string

AvailableProviders lists the currently registered provider IDs.

func CachedModelCountForProvider added in v0.1.3

func CachedModelCountForProvider(ctx context.Context, provider string) int

CachedModelCountForProvider returns the on-disk catalog model count for a gateway.

func CatalogProviderID added in v0.1.3

func CatalogProviderID(provider string) string

CatalogProviderID canonicalizes a host-facing provider into the catalog-facing id. Setup gateways stay on their registry ids; provider aliases like gemini/grok map to their catalog owners google/xai.

func ChatProvider added in v0.1.3

func ChatProvider(ctx context.Context) (client.Provider, error)

ChatProvider builds the configured chat provider without requiring callers to load runtime state first. Host applications should prefer this over reaching into lower-level setup/config packages.

func ClearActiveSelection

func ClearActiveSelection(ctx context.Context) error

ClearActiveSelection removes active provider/model from provider.json.

func CommitCredential

func CommitCredential(ctx context.Context, inference CredentialInference, secret string) error

CommitCredential runs format + provider validation + probe (no persistence).

func CredentialEnvKeys added in v0.1.3

func CredentialEnvKeys(providerID string) []string

CredentialEnvKeys returns the credential env vars associated with a provider, including registry fallbacks and compatibility aliases.

func DefaultModelForProvider added in v0.1.3

func DefaultModelForProvider(ctx context.Context, provider string) string

DefaultModelForProvider returns the preferred model for a provider using cache first, then live discovery when credentials are configured.

func DefaultModelProviderFilter

func DefaultModelProviderFilter(ctx context.Context) string

DefaultModelProviderFilter returns the catalog provider id to use when listing models with no explicit provider (e.g. /config model picker after paste-key). Order: provider.json default → first configured deployment (stable sort by id).

func DefaultPaths

func DefaultPaths() (catalogPath, providerPath string)

DefaultPaths reports standard eyrie paths on disk.

func DeploymentRoutingEnabled added in v0.1.3

func DeploymentRoutingEnabled(ctx context.Context, override *bool) bool

DeploymentRoutingEnabled resolves runtime routing policy plus an optional host override.

func DeploymentStatus added in v0.1.3

func DeploymentStatus(ctx context.Context, activeModel string) (setup.StatusReport, error)

DeploymentStatus returns deployment-routing diagnostics for host UIs.

func FormatApplyCredentialsSummary added in v0.1.3

func FormatApplyCredentialsSummary(result *setup.ApplyCredentialsResult) string

FormatApplyCredentialsSummary summarizes provider apply results for host UIs.

func FormatDeploymentStatus added in v0.1.3

func FormatDeploymentStatus(report setup.StatusReport) string

FormatDeploymentStatus renders a deployment-routing diagnostics report for host UIs.

func FormatPreflightReport

func FormatPreflightReport(r PreflightReport) string

FormatPreflightReport returns human-readable preflight output.

func FormatSetupError

func FormatSetupError(providerID string, err error) error

FormatSetupError maps provider setup failures to user-facing hints.

func GatewayDisplayName added in v0.1.3

func GatewayDisplayName(providerID string) string

GatewayDisplayName returns the registry display label for a setup gateway.

func GatewayNeedsRegion added in v0.1.3

func GatewayNeedsRegion(providerID string) bool

GatewayNeedsRegion reports whether a gateway still requires a region selection.

func GatewayRegionLabel added in v0.1.3

func GatewayRegionLabel(providerID string) string

GatewayRegionLabel returns the saved normalized region for gateways that require one.

func HasConfiguredDeployment added in v0.1.3

func HasConfiguredDeployment(ctx context.Context) bool

HasConfiguredDeployment reports whether the engine has at least one usable deployment.

func HasStoredCredential added in v0.1.3

func HasStoredCredential(ctx context.Context, providerID string) bool

HasStoredCredential reports whether the OS secret store has a usable secret for a gateway.

func IsSetupGateway added in v0.1.3

func IsSetupGateway(providerID string) bool

IsSetupGateway reports whether the provider id resolves to a registered setup gateway.

func ModelsForProvider

func ModelsForProvider(ctx context.Context, provider string) ([]catalog.ModelCatalogEntry, error)

ModelsForProvider loads the catalog cache and returns models for provider. Prefer ListModels for host UIs (registry-aware live vs cache).

func NormalizeProviderID added in v0.1.3

func NormalizeProviderID(provider string) string

NormalizeProviderID resolves catalog aliases and host-facing variants to the runtime provider identifier used by Eyrie adapters and setup gateways.

func PreferredProvider added in v0.1.3

func PreferredProvider(ctx context.Context) string

PreferredProvider returns the runtime-owned provider choice when a host has not pinned one explicitly. Active selection wins first, then inferred model ownership, then configured providers ordered by runtime preference, and finally credential detection as a last resort.

func PrepareCredentialDiscovery added in v0.1.3

func PrepareCredentialDiscovery(ctx context.Context)

PrepareCredentialDiscovery applies runtime-owned gateway env derivations before probe/discovery.

func PrimaryAPIKeyEnv

func PrimaryAPIKeyEnv(deploymentID string) string

PrimaryAPIKeyEnv returns the main env var for a deployment ID from the catalog.

func ProbeCredential

func ProbeCredential(ctx context.Context, envKey, secret string) error

ProbeCredential validates a key against the provider HTTP API.

func ProviderIDForDeployment

func ProviderIDForDeployment(deploymentID string) string

ProviderIDForDeployment maps a deployment id to catalog provider id.

func RefreshGatewayCatalog added in v0.1.3

func RefreshGatewayCatalog(ctx context.Context, providerID string) (string, error)

RefreshGatewayCatalog fetches live models for one gateway and updates the cached catalog.

func ResolveCanonicalModel added in v0.1.3

func ResolveCanonicalModel(ctx context.Context, model string) string

ResolveCanonicalModel maps aliases/native IDs to canonical catalog model IDs.

func RoutingPreview added in v0.1.3

func RoutingPreview(ctx context.Context, model string) (string, error)

RoutingPreview returns the effective routing preview JSON for a model ID.

func SaveCredential

func SaveCredential(ctx context.Context, inference CredentialInference, secret string) error

SaveCredential validates, stores in the OS secret store, then probes the provider API. The key is persisted before the probe so a network or auth failure does not discard user input.

func SetActiveModel

func SetActiveModel(ctx context.Context, modelID string) error

SetActiveModel persists the user's model choice to provider.json.

func SetActiveProvider

func SetActiveProvider(ctx context.Context, provider string) error

SetActiveProvider persists active_provider to provider.json.

func SetCredential

func SetCredential(ctx context.Context, envKey, secret string) error

SetCredential stores a provider secret (env var name + value). Never log the secret argument.

func SetGatewayRegion added in v0.1.3

func SetGatewayRegion(providerID, region string) error

SetGatewayRegion persists a normalized gateway region and updates derived env/base-url state.

func SetupGatewayCredentialEnv added in v0.1.3

func SetupGatewayCredentialEnv(providerID string) string

SetupGatewayCredentialEnv returns the primary credential env var for a setup gateway.

func SetupGatewayID added in v0.1.3

func SetupGatewayID(provider string) string

SetupGatewayID canonicalizes a host-facing setup-gateway id through runtime rules.

func SetupGateways added in v0.1.3

func SetupGateways() []string

SetupGateways returns the registry-backed gateway ids users configure in setup UIs.

func SetupUIFromCatalog

func SetupUIFromCatalog(ctx context.Context, providerFilter string) (*setup.SetupUI, error)

SetupUIFromCatalog builds provider/model picker rows from the current catalog cache.

func ShouldClearSelectionAfterCredentialRemove added in v0.1.3

func ShouldClearSelectionAfterCredentialRemove(ctx context.Context, removedProvider string) bool

ShouldClearSelectionAfterCredentialRemove reports whether removing a gateway key invalidates the active selection.

func SyncSelectionWithCredentials added in v0.1.3

func SyncSelectionWithCredentials(ctx context.Context)

SyncSelectionWithCredentials clears stale persisted selection when the selected gateway no longer has usable credentials.

func ValidateKeyFormat

func ValidateKeyFormat(secret string) error

ValidateKeyFormat rejects empty/placeholder keys before provider selection.

Types

type ApplyResult

type ApplyResult struct {
	Catalog      *catalog.RefreshResult
	Provider     *config.ProviderConfig
	ProviderPath string
	RoutingJSON  string
	Setup        *setup.SetupUI
}

ApplyResult summarizes an Apply call.

func Apply

func Apply(ctx context.Context, creds catalog.Credentials) (*ApplyResult, error)

Apply discovers the model catalog and writes ~/.eyrie/provider.json (routing only; secrets stay in env).

func Discover

func Discover(ctx context.Context) (*ApplyResult, error)

Discover runs a full catalog refresh then reloads runtime state.

type ChatTransport added in v0.1.3

type ChatTransport struct {
	Selection SelectionState
	Provider  client.Provider
}

ChatTransport is the runtime-owned chat transport plan that host apps adapt into their local session/client abstractions.

func ResolveChatTransport added in v0.1.3

func ResolveChatTransport(ctx context.Context, opts ChatTransportOpts) (ChatTransport, error)

ResolveChatTransport resolves the effective selection and constructs the runtime-owned provider transport for both deployment-routed and direct provider execution.

func ResolveChatTransportFromSelection added in v0.1.3

func ResolveChatTransportFromSelection(ctx context.Context, selection SelectionState) (ChatTransport, error)

ResolveChatTransportFromSelection constructs a transport from an already resolved selection state, avoiding redundant provider/model discovery.

type ChatTransportOpts added in v0.1.3

type ChatTransportOpts struct {
	Selection SelectionOpts
}

ChatTransportOpts supplies host-side overrides while transport ownership moves into the runtime package.

type CredentialInference

type CredentialInference = config.CredentialInference

Credential types re-exported for host apps.

func InferCredentialsFromAPIKey

func InferCredentialsFromAPIKey(ctx context.Context, secret string) []CredentialInference

InferCredentialsFromAPIKey is deprecated; use InferenceForProvider after gateway selection.

func InferenceForProvider

func InferenceForProvider(providerID string) (CredentialInference, error)

InferenceForProvider returns save metadata for a gateway selected in setup UI.

func LocalCredentialInference

func LocalCredentialInference(providerID string) (CredentialInference, error)

LocalCredentialInference returns setup metadata for no-key providers.

type CredentialProviderOption

type CredentialProviderOption = config.CredentialProviderOption

Credential types re-exported for host apps.

func ListCredentialProviders

func ListCredentialProviders() []CredentialProviderOption

ListCredentialProviders returns all registry providers for setup UIs.

type CredentialResolveResult

type CredentialResolveResult = config.CredentialResolveResult

Credential types re-exported for host apps.

func ResolveCredential

func ResolveCredential(ctx context.Context, secret string) CredentialResolveResult

ResolveCredential validates format and lists registered providers (gateway must be chosen first).

type CredentialTarget

type CredentialTarget struct {
	ProviderID   string
	DeploymentID string
	EnvVar       string
	Set          bool
}

CredentialTarget is one API key slot in a host /config UI.

type DeploymentRow

type DeploymentRow struct {
	ID         string
	Name       string
	ProviderID string
	Configured bool
	Status     string
	PrimaryEnv string
}

DeploymentRow is a deployment plus env credential status.

type GatewayStatus added in v0.1.3

type GatewayStatus struct {
	ID                      string `json:"id"`
	DisplayName             string `json:"display_name"`
	HasStoredCredential     bool   `json:"has_stored_credential"`
	HasConfiguredDeployment bool   `json:"has_configured_deployment"`
	ModelCount              int    `json:"model_count"`
	Active                  bool   `json:"active"`
	RegionLabel             string `json:"region_label,omitempty"`
	RegionRequired          bool   `json:"region_required,omitempty"`
}

GatewayStatus is one setup-gateway row for host UIs.

func GatewayStatuses added in v0.1.3

func GatewayStatuses(ctx context.Context, opts GatewayStatusOpts) []GatewayStatus

GatewayStatuses returns runtime-owned setup-gateway summaries for host /config UIs.

type GatewayStatusOpts added in v0.1.3

type GatewayStatusOpts struct {
	ActiveProvider string
	ActiveModel    string
}

GatewayStatusOpts controls runtime-owned gateway summaries for host setup UIs.

type ListModelSource

type ListModelSource string

ListModelSource selects cache vs live model listing.

const (
	ListSourceAuto  ListModelSource = "auto"
	ListSourceCache ListModelSource = "cache"
	ListSourceLive  ListModelSource = "live"
)

type ListModelsOpts

type ListModelsOpts struct {
	ProviderID string
	Source     ListModelSource
	Refresh    bool
}

ListModelsOpts configures unified model listing for host UIs.

type ModelEntry

type ModelEntry struct {
	ID               string  `json:"id"`
	DisplayName      string  `json:"display_name"`
	Owner            string  `json:"owner,omitempty"`
	ProviderID       string  `json:"provider_id"`
	ContextWindow    int     `json:"context_window,omitempty"`
	InputPricePer1M  float64 `json:"input_price_per_1m,omitempty"`
	OutputPricePer1M float64 `json:"output_price_per_1m,omitempty"`
	Source           string  `json:"source"`
	Installed        bool    `json:"installed,omitempty"`
}

ModelEntry is one row for host model pickers.

func ListModels

func ListModels(ctx context.Context, opts ListModelsOpts) ([]ModelEntry, error)

ListModels returns models for a provider using registry-driven source selection.

type PreflightCheck

type PreflightCheck struct {
	Name   string          `json:"name"`
	Status PreflightStatus `json:"status"`
	Detail string          `json:"detail"`
}

PreflightCheck is one readiness row.

type PreflightReport

type PreflightReport struct {
	Ready  bool             `json:"ready"`
	Checks []PreflightCheck `json:"checks"`
}

PreflightReport summarizes whether hawk can chat.

func Preflight

func Preflight(ctx context.Context) PreflightReport

Preflight evaluates catalog, credentials, model selection, and optional live model access.

type PreflightStatus

type PreflightStatus string

PreflightStatus is ok, warn, or fail.

const (
	PreflightOK   PreflightStatus = "ok"
	PreflightWarn PreflightStatus = "warn"
	PreflightFail PreflightStatus = "fail"
)

type ProviderSetupOption

type ProviderSetupOption struct {
	Action string `json:"action"`
	Label  string `json:"label"`
}

ProviderSetupOption is one hub row in host /config.

func ListProviderSetupOptions

func ListProviderSetupOptions(ctx context.Context) []ProviderSetupOption

ListProviderSetupOptions returns hub rows for host /config UIs.

type Runtime

type Runtime struct {
	Catalog      *catalog.CompiledCatalogV1
	Provider     *config.ProviderConfig
	ProviderPath string
}

Runtime is a loaded eyrie control plane: catalog cache + routing + env-backed credentials.

func Load

func Load(ctx context.Context) (*Runtime, error)

Load reads the on-disk catalog and provider config without network refresh.

func (*Runtime) ChatProvider

func (r *Runtime) ChatProvider(ctx context.Context) (client.Provider, error)

ChatProvider builds the LLM client (deployment router when configured).

func (*Runtime) CredentialTargets

func (r *Runtime) CredentialTargets() []CredentialTarget

CredentialTargets lists provider-facing API key env vars for simple UIs.

func (*Runtime) DeploymentRows

func (r *Runtime) DeploymentRows() ([]DeploymentRow, error)

DeploymentRows lists deployments with credential status from env (not from provider.json secrets).

func (*Runtime) ModelEntriesForProvider

func (r *Runtime) ModelEntriesForProvider(provider string) []catalog.ModelCatalogEntry

ModelEntriesForProvider returns models for a provider from this runtime's catalog snapshot.

func (*Runtime) ModelIDs

func (r *Runtime) ModelIDs() []string

ModelIDs returns sorted canonical model IDs from the catalog.

func (*Runtime) ProviderConfigJSON

func (r *Runtime) ProviderConfigJSON() (string, error)

ProviderConfigJSON returns provider.json as indented JSON.

func (*Runtime) RoutingPreviewJSON

func (r *Runtime) RoutingPreviewJSON(model string) (string, error)

RoutingPreviewJSON returns effective routing for a model ID.

type SelectionOpts added in v0.1.3

type SelectionOpts struct {
	ProviderOverride string
	ModelOverride    string
	// DeploymentRoutingOverride lets a host force the routing mode while the
	// migration to pure engine-owned policy is in progress.
	DeploymentRoutingOverride *bool
}

SelectionOpts supplies optional host overrides for provider/model selection. Empty overrides mean "use engine-persisted/default selection".

type SelectionState added in v0.1.3

type SelectionState struct {
	Provider                string `json:"provider"`
	Model                   string `json:"model"`
	HasConfiguredDeployment bool   `json:"has_configured_deployment"`
	DeploymentRouting       bool   `json:"deployment_routing"`
}

SelectionState is the engine-resolved provider/model selection for chat.

func EffectiveSelection added in v0.1.3

func EffectiveSelection(ctx context.Context, opts SelectionOpts) SelectionState

EffectiveSelection resolves the provider/model that chat should use after applying persisted selection, optional host overrides, credential-aware fallback, and optional canonicalization.

Jump to

Keyboard shortcuts

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