kit/plans/06-auth-model-management.md

Plan 06: Auth & Model Management APIs

Priority: P2 Effort: Medium Goal: Expose provider management, model validation, and API key handling in the SDK; CLI auth commands consume SDK APIs

Background

Pi exports AuthStorage, ModelRegistry, SettingsManager for programmatic auth/model management. Kit has this internally (internal/models/registry.go, internal/auth/credentials.go, internal/models/providers.go) but none is exposed through the SDK.

Prerequisites

• Plan 00 (Create pkg/kit/)
• Plan 02 (Richer type exports)

Step-by-Step

Step 1: Export model registry functions

File: pkg/kit/models.go (new)

package kit

import (
    "fmt"
    "github.com/mark3labs/kit/internal/models"
)

// LookupModel returns information about a model, or nil if unknown.
func LookupModel(provider, modelID string) *ModelInfo {
    return models.GetGlobalRegistry().LookupModel(provider, modelID)
}

// GetSupportedProviders returns all known provider names.
func GetSupportedProviders() []string {
    return models.GetGlobalRegistry().GetSupportedProviders()
}

// GetModelsForProvider returns all known models for a provider.
func GetModelsForProvider(provider string) (map[string]ModelInfo, error) {
    return models.GetGlobalRegistry().GetModelsForProvider(provider)
}

// GetProviderInfo returns information about a provider (env vars, API URL, etc.).
func GetProviderInfo(provider string) *ProviderInfo {
    return models.GetGlobalRegistry().GetProviderInfo(provider)
}

// ValidateEnvironment checks if required API keys are set for a provider.
func ValidateEnvironment(provider string, apiKey string) error {
    return models.GetGlobalRegistry().ValidateEnvironment(provider, apiKey)
}

// SuggestModels returns model names similar to an invalid model string.
func SuggestModels(provider, invalidModel string) []string {
    return models.GetGlobalRegistry().SuggestModels(provider, invalidModel)
}

// RefreshModelRegistry reloads the model database from models.dev.
func RefreshModelRegistry() {
    models.ReloadGlobalRegistry()
}

// ParseModelString splits a "provider/model" string into components.
func ParseModelString(modelString string) (provider, model string, err error) {
    return models.ParseModelString(modelString)
}

// CheckProviderReady validates that a provider is properly configured.
func CheckProviderReady(provider string) error {
    info := models.GetGlobalRegistry().GetProviderInfo(provider)
    if info == nil {
        return fmt.Errorf("unknown provider: %s", provider)
    }
    return models.GetGlobalRegistry().ValidateEnvironment(provider, "")
}

Step 2: Add model info to Kit instance

File: pkg/kit/kit.go

// GetModel returns the current model string (e.g., "anthropic/claude-sonnet-4-5-20250929").
func (m *Kit) GetModel() string {
    return m.modelString
}

// GetModelInfo returns detailed information about the current model.
// Returns nil if the model is not in the registry.
func (m *Kit) GetModelInfo() *ModelInfo {
    provider, modelID, err := models.ParseModelString(m.modelString)
    if err != nil {
        return nil
    }
    return models.GetGlobalRegistry().LookupModel(provider, modelID)
}

Step 3: Export auth credential management

File: pkg/kit/auth.go (new)

package kit

import "github.com/mark3labs/kit/internal/auth"

// CredentialManager manages API keys and OAuth credentials.
type CredentialManager = auth.CredentialManager

// NewCredentialManager creates a credential manager.
func NewCredentialManager() (*CredentialManager, error) {
    return auth.NewCredentialManager()
}

// HasAnthropicCredentials checks if Anthropic credentials are stored.
func HasAnthropicCredentials() bool {
    cm, err := auth.NewCredentialManager()
    if err != nil {
        return false
    }
    return cm.GetAnthropicCredentials() != nil
}

// GetAnthropicAPIKey resolves the Anthropic API key using the standard
// resolution order: stored credentials -> ANTHROPIC_API_KEY env var.
func GetAnthropicAPIKey() string {
    key, err := auth.GetAnthropicAPIKey("")
    if err != nil {
        return ""
    }
    return key
}

Step 4: App-as-Consumer — CLI commands use SDK APIs

Currently CLI commands like kit models, kit update-models, and provider validation logic directly import internal/models and internal/auth. They should use pkg/kit functions instead.

File: cmd/root.go or wherever model validation happens

// Before:
import "github.com/mark3labs/kit/internal/models"
registry := models.GetGlobalRegistry()
info := registry.LookupModel(provider, model)

// After:
import kit "github.com/mark3labs/kit/pkg/kit"
info := kit.LookupModel(provider, model)

File: cmd/ auth-related commands

// Before:
import "github.com/mark3labs/kit/internal/auth"
cm, _ := auth.NewCredentialManager()

// After:
import kit "github.com/mark3labs/kit/pkg/kit"
cm, _ := kit.NewCredentialManager()

Since these are type aliases, existing code continues to work during gradual migration.

Step 5: Write tests and verify

go build -o output/kit ./cmd/kit
go test -race ./...
go vet ./...

Files Changed Summary

Action	File	Change
CREATE	pkg/kit/models.go	Model registry, parsing, validation, suggestions
CREATE	pkg/kit/auth.go	Credential management exports
EDIT	pkg/kit/kit.go	Add GetModel(), GetModelInfo()
EDIT	cmd/	Migrate to use pkg/kit functions (gradual)

Verification Checklist

• ParseModelString handles "provider/model" format
• GetSupportedProviders returns provider list
• LookupModel returns info for known models
• CheckProviderReady gives clear error messages
• CLI commands use SDK functions instead of internal imports