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
- func ActiveGateway(ctx context.Context) string
- func ActiveModel(ctx context.Context) string
- func ActiveProvider(ctx context.Context) string
- func ActiveProviderID(provider string) string
- func AllModelIDs(ctx context.Context) ([]string, error)
- func ApplyCredentialsForProvider(ctx context.Context, providerID string) (*setup.ApplyCredentialsResult, error)
- func ApplyGatewayEnv(ctx context.Context, providerID string)
- func AvailableProviders() []string
- func CachedModelCountForProvider(ctx context.Context, provider string) int
- func CatalogProviderID(provider string) string
- func ChatProvider(ctx context.Context) (client.Provider, error)
- func ClearActiveSelection(ctx context.Context) error
- func CommitCredential(ctx context.Context, inference CredentialInference, secret string) error
- func CredentialEnvKeys(providerID string) []string
- func DefaultModelForProvider(ctx context.Context, provider string) string
- func DefaultModelProviderFilter(ctx context.Context) string
- func DefaultPaths() (catalogPath, providerPath string)
- func DeploymentRoutingEnabled(ctx context.Context, override *bool) bool
- func DeploymentStatus(ctx context.Context, activeModel string) (setup.StatusReport, error)
- func FormatApplyCredentialsSummary(result *setup.ApplyCredentialsResult) string
- func FormatDeploymentStatus(report setup.StatusReport) string
- func FormatPreflightReport(r PreflightReport) string
- func FormatSetupError(providerID string, err error) error
- func GatewayDisplayName(providerID string) string
- func GatewayNeedsRegion(providerID string) bool
- func GatewayRegionLabel(providerID string) string
- func HasConfiguredDeployment(ctx context.Context) bool
- func HasStoredCredential(ctx context.Context, providerID string) bool
- func IsSetupGateway(providerID string) bool
- func ModelsForProvider(ctx context.Context, provider string) ([]catalog.ModelCatalogEntry, error)
- func NormalizeProviderID(provider string) string
- func PreferredProvider(ctx context.Context) string
- func PrepareCredentialDiscovery(ctx context.Context)
- func PrimaryAPIKeyEnv(deploymentID string) string
- func ProbeCredential(ctx context.Context, envKey, secret string) error
- func ProviderIDForDeployment(deploymentID string) string
- func RefreshGatewayCatalog(ctx context.Context, providerID string) (string, error)
- func ResolveCanonicalModel(ctx context.Context, model string) string
- func RoutingPreview(ctx context.Context, model string) (string, error)
- func SaveCredential(ctx context.Context, inference CredentialInference, secret string) error
- func SetActiveModel(ctx context.Context, modelID string) error
- func SetActiveProvider(ctx context.Context, provider string) error
- func SetCredential(ctx context.Context, envKey, secret string) error
- func SetGatewayRegion(providerID, region string) error
- func SetupGatewayCredentialEnv(providerID string) string
- func SetupGatewayID(provider string) string
- func SetupGateways() []string
- func SetupUIFromCatalog(ctx context.Context, providerFilter string) (*setup.SetupUI, error)
- func ShouldClearSelectionAfterCredentialRemove(ctx context.Context, removedProvider string) bool
- func SyncSelectionWithCredentials(ctx context.Context)
- func ValidateKeyFormat(secret string) error
- type ApplyResult
- type ChatTransport
- type ChatTransportOpts
- type CredentialInference
- type CredentialProviderOption
- type CredentialResolveResult
- type CredentialTarget
- type DeploymentRow
- type GatewayStatus
- type GatewayStatusOpts
- type ListModelSource
- type ListModelsOpts
- type ModelEntry
- type PreflightCheck
- type PreflightReport
- type PreflightStatus
- type ProviderSetupOption
- type Runtime
- func (r *Runtime) ChatProvider(ctx context.Context) (client.Provider, error)
- func (r *Runtime) CredentialTargets() []CredentialTarget
- func (r *Runtime) DeploymentRows() ([]DeploymentRow, error)
- func (r *Runtime) ModelEntriesForProvider(provider string) []catalog.ModelCatalogEntry
- func (r *Runtime) ModelIDs() []string
- func (r *Runtime) ProviderConfigJSON() (string, error)
- func (r *Runtime) RoutingPreviewJSON(model string) (string, error)
- type SelectionOpts
- type SelectionState
Constants ¶
const (
GatewayXiaomiTokenPlan = "xiaomi_mimo_token_plan"
)
Variables ¶
This section is empty.
Functions ¶
func ActiveGateway ¶ added in v0.1.3
ActiveGateway returns the selected setup gateway derived from active provider/model state.
func ActiveModel ¶
ActiveModel returns the selected model from provider.json.
func ActiveProvider ¶
ActiveProvider returns the selected provider from provider.json.
func ActiveProviderID ¶ added in v0.1.3
ActiveProviderID canonicalizes a host-facing provider/gateway id through the runtime provider-id rules used by Eyrie.
func AllModelIDs ¶
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
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
CachedModelCountForProvider returns the on-disk catalog model count for a gateway.
func CatalogProviderID ¶ added in v0.1.3
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
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 ¶
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
CredentialEnvKeys returns the credential env vars associated with a provider, including registry fallbacks and compatibility aliases.
func DefaultModelForProvider ¶ added in v0.1.3
DefaultModelForProvider returns the preferred model for a provider using cache first, then live discovery when credentials are configured.
func DefaultModelProviderFilter ¶
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
DeploymentRoutingEnabled resolves runtime routing policy plus an optional host override.
func DeploymentStatus ¶ added in v0.1.3
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 ¶
FormatSetupError maps provider setup failures to user-facing hints.
func GatewayDisplayName ¶ added in v0.1.3
GatewayDisplayName returns the registry display label for a setup gateway.
func GatewayNeedsRegion ¶ added in v0.1.3
GatewayNeedsRegion reports whether a gateway still requires a region selection.
func GatewayRegionLabel ¶ added in v0.1.3
GatewayRegionLabel returns the saved normalized region for gateways that require one.
func HasConfiguredDeployment ¶ added in v0.1.3
HasConfiguredDeployment reports whether the engine has at least one usable deployment.
func HasStoredCredential ¶ added in v0.1.3
HasStoredCredential reports whether the OS secret store has a usable secret for a gateway.
func IsSetupGateway ¶ added in v0.1.3
IsSetupGateway reports whether the provider id resolves to a registered setup gateway.
func ModelsForProvider ¶
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
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
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
PrepareCredentialDiscovery applies runtime-owned gateway env derivations before probe/discovery.
func PrimaryAPIKeyEnv ¶
PrimaryAPIKeyEnv returns the main env var for a deployment ID from the catalog.
func ProbeCredential ¶
ProbeCredential validates a key against the provider HTTP API.
func ProviderIDForDeployment ¶
ProviderIDForDeployment maps a deployment id to catalog provider id.
func RefreshGatewayCatalog ¶ added in v0.1.3
RefreshGatewayCatalog fetches live models for one gateway and updates the cached catalog.
func ResolveCanonicalModel ¶ added in v0.1.3
ResolveCanonicalModel maps aliases/native IDs to canonical catalog model IDs.
func RoutingPreview ¶ added in v0.1.3
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 ¶
SetActiveModel persists the user's model choice to provider.json.
func SetActiveProvider ¶
SetActiveProvider persists active_provider to provider.json.
func SetCredential ¶
SetCredential stores a provider secret (env var name + value). Never log the secret argument.
func SetGatewayRegion ¶ added in v0.1.3
SetGatewayRegion persists a normalized gateway region and updates derived env/base-url state.
func SetupGatewayCredentialEnv ¶ added in v0.1.3
SetupGatewayCredentialEnv returns the primary credential env var for a setup gateway.
func SetupGatewayID ¶ added in v0.1.3
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 ¶
SetupUIFromCatalog builds provider/model picker rows from the current catalog cache.
func ShouldClearSelectionAfterCredentialRemove ¶ added in v0.1.3
ShouldClearSelectionAfterCredentialRemove reports whether removing a gateway key invalidates the active selection.
func SyncSelectionWithCredentials ¶ added in v0.1.3
SyncSelectionWithCredentials clears stale persisted selection when the selected gateway no longer has usable credentials.
func ValidateKeyFormat ¶
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).
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 ¶
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
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 ¶
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 (*Runtime) ChatProvider ¶
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) ProviderConfigJSON ¶
ProviderConfigJSON returns provider.json as indented JSON.
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.