llm

Documentation

Overview

Package llm is the catwalk client wrapper and model-resolution layer.

Phase 1 scope

This package provides two things:

1. A Client that wraps the catwalk catalog. On construction it loads the catwalk embedded snapshot immediately (so there is always offline-capable model metadata), then fires a background ETag-gated refresh from the live catwalk service. Internally it delegates to catalog.Catalog.

2. A [Resolve] helper that looks up a provider/model pair in the catalog and returns the corresponding catalog.Entry. Existing callers that already hold a *catalog.Catalog can keep using it directly; this wrapper is for new code that wants a narrower surface.

Phase 2 adds ResolveProviderModel in provider_factory.go, which constructs fantasy.LanguageModel values while the existing provider stream adapters stay in place for the Phase 3 turn-loop migration.

Boundaries

This package imports github.com/cfbender/hygge/internal/catalog and the standard library only. It must not import internal/agent, internal/store, internal/provider, or internal/cost.

Index

• type Client
  • func New() (*Client, error)
  • func NewWithOptions(opts Options) (*Client, error)
  • func (c *Client) Catalog() *catalog.Catalog
  • func (c *Client) Close() error
  • func (c *Client) EmbeddedProviders() []string
  • func (c *Client) Refresh(ctx context.Context) error
  • func (c *Client) Resolve(providerID, modelID string) (catalog.Entry, bool)
  • func (c *Client) WarmLog()
• type Options
• type ProviderResolution
  • func ResolveProviderModel(ctx context.Context, providerID, modelID string, opts map[string]any, ...) (ProviderResolution, error)

Types

type Client

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

Client is a thin wrapper around catalog.Catalog. It loads the catwalk embedded snapshot on construction and optionally performs a live ETag-gated refresh in the background.

Use New or NewWithOptions to construct one; the zero value is not usable.

func New

func New() (*Client, error)

New constructs a production Client using default options. It always returns a usable Client: the embedded snapshot is loaded immediately so offline operation is always possible.

Returns an error only if the embedded catwalk provider data is missing or corrupt, which would be a build-time bug.

func NewWithOptions

func NewWithOptions(opts Options) (*Client, error)

NewWithOptions constructs a Client with the given options.

func (*Client) Catalog

func (c *Client) Catalog() *catalog.Catalog

Catalog returns the underlying *catalog.Catalog handle. Useful for callers that need the full catalog API (e.g. listing all models for a provider).

func (*Client) Close

func (c *Client) Close() error

Close stops any periodic-refresh ticker goroutine. Should be deferred by long-lived callers (e.g. the CLI runtime).

func (*Client) EmbeddedProviders

func (c *Client) EmbeddedProviders() []string

EmbeddedProviders returns a summary of the providers available in the embedded snapshot. Useful for startup diagnostics.

func (*Client) Refresh

func (c *Client) Refresh(ctx context.Context) error

Refresh forces a live fetch and updates the in-memory and on-disk snapshot. If the catwalk service responds 304 Not Modified, Refresh returns nil — the snapshot is already current.

func (*Client) Resolve

func (c *Client) Resolve(providerID, modelID string) (catalog.Entry, bool)

Resolve returns the catalog.Entry for (providerID, modelID). Returns ok=false when no entry is found. Both arguments are case-insensitive (delegated to catalog.Catalog.Lookup).

func (*Client) WarmLog

func (c *Client) WarmLog()

WarmLog logs the embedded-snapshot load result at Debug level. Called from the CLI bootstrap to surface catalog readiness.

type Options

type Options struct {
	// StateDir is the directory for the on-disk snapshot cache.
	// Empty defaults to the XDG state directory (see catalog.LoadOptions).
	StateDir string

	// BaseURL overrides the catwalk service URL.  Empty defaults to
	// the catalog package default (the public catwalk API).
	// Tests point this at an httptest server.
	BaseURL string

	// HTTPClient overrides the HTTP client used for live fetches.
	// Nil uses a client with the catalog package's default timeout.
	HTTPClient *http.Client

	// BackgroundRefresh enables the on-startup goroutine that fetches
	// a fresh snapshot when the disk cache is stale.  Defaults to true.
	// Set to false in tests for determinism.
	BackgroundRefresh *bool

	// RefreshInterval, when positive, starts a periodic ticker that
	// refreshes the catalog at that cadence.  Zero means no periodic
	// refresh.
	RefreshInterval time.Duration

	// Now is an injectable clock for tests.  Nil uses time.Now.
	Now func() time.Time
}

Options configures a Client. The zero value yields sensible production defaults.

type ProviderResolution

type ProviderResolution struct {
	Provider fantasy.Provider
	Model    fantasy.LanguageModel
	Metadata provider.Model
}

ProviderResolution is the Phase 2 bridge result for constructing a fantasy-backed model while preserving metadata the existing runtime expects.

func ResolveProviderModel

func ResolveProviderModel(ctx context.Context, providerID, modelID string, opts map[string]any, cat *catalog.Catalog) (ProviderResolution, error)

ResolveProviderModel builds a fantasy provider/model pair for the given hygge provider id and model id.