Skip to content

Latest commit

 

History

History
325 lines (231 loc) · 9.53 KB

API.md

File metadata and controls

325 lines (231 loc) · 9.53 KB

Starmap API Reference

Auto-generated API documentation for the Starmap Go package

This document provides a complete API reference for Starmap's public interfaces. For architectural details and design patterns, see ARCHITECTURE.md. For usage examples and getting started, see README.md.

Quick Navigation

starmap

import "github.com/agentstation/starmap"

Package starmap provides the main entry point for the Starmap AI model catalog system. It offers a high-level interface for managing AI model catalogs with automatic updates, event hooks, and provider synchronization capabilities.

Starmap wraps the underlying catalog system with additional features including: - Automatic background synchronization with provider APIs - Event hooks for model changes (added, updated, removed) - Thread-safe catalog access with copy-on-read semantics - Flexible configuration through functional options - Support for multiple data sources and merge strategies

Example usage:

// Create a starmap instance with default settings
sm, err := starmap.New()
if err != nil {
    log.Fatal(err)
}
defer sm.AutoUpdatesOff()

// Register event hooks
sm.OnModelAdded(func(model catalogs.Model) {
    log.Printf("New model: %s", model.ID)
})

// Get catalog (returns a copy for thread safety)
catalog, err := sm.Catalog()
if err != nil {
    log.Fatal(err)
}

// Access models
models := catalog.Models()
for _, model := range models.List() {
    fmt.Printf("Model: %s - %s\n", model.ID, model.Name)
}

// Manually trigger sync
result, err := sm.Sync(ctx, WithProviders("openai", "anthropic"))
if err != nil {
    log.Fatal(err)
}

// Configure with custom options
sm, err = starmap.New(
    WithAutoUpdateInterval(30 * time.Minute),
    WithLocalPath("./custom-catalog"),
    WithAutoUpdates(true),
)

Package starmap provides a unified AI model catalog system with automatic updates, event hooks, and support for multiple storage backends.

Index

type AutoUpdateFunc

AutoUpdateFunc is a function that updates the catalog.

type AutoUpdateFunc func(catalogs.Catalog) (catalogs.Catalog, error)

type AutoUpdater

AutoUpdater provides controls for automatic catalog updates.

type AutoUpdater interface {
    // AutoUpdatesOn begins automatic updates if configured
    AutoUpdatesOn() error

    // AutoUpdatesOff stops automatic updates
    AutoUpdatesOff() error
}

type Catalog

Catalog provides copy-on-read access to the catalog.

type Catalog interface {
    Catalog() (catalogs.Catalog, error)
}

type Client

Client manages a catalog with automatic updates and event hooks.

type Client interface {

    // Catalog provides copy-on-read access to the catalog
    Catalog

    // Updater handles catalog update and sync operations
    Updater

    // Persistence handles catalog persistence operations
    Persistence

    // AutoUpdater provides access to automatic update controls
    AutoUpdater

    // Hooks provides access to event callback registration
    Hooks
}

func New

func New(opts ...Option) (Client, error)

New creates a new Client instance with the given options.

type Hooks

Hooks provides event callback registration for catalog changes.

type Hooks interface {
    // OnModelAdded registers a callback for when models are added
    OnModelAdded(ModelAddedHook)

    // OnModelUpdated registers a callback for when models are updated
    OnModelUpdated(ModelUpdatedHook)

    // OnModelRemoved registers a callback for when models are removed
    OnModelRemoved(ModelRemovedHook)
}

type ModelAddedHook

ModelAddedHook is called when a model is added to the catalog.

type ModelAddedHook func(model catalogs.Model)

type ModelRemovedHook

ModelRemovedHook is called when a model is removed from the catalog.

type ModelRemovedHook func(model catalogs.Model)

type ModelUpdatedHook

ModelUpdatedHook is called when a model is updated in the catalog.

type ModelUpdatedHook func(old, updated catalogs.Model)

type Option

Option is a function that configures a Starmap instance.

type Option func(*options) error

func WithAutoUpdateFunc

func WithAutoUpdateFunc(fn AutoUpdateFunc) Option

WithAutoUpdateFunc configures a custom function for updating the catalog.

func WithAutoUpdateInterval

func WithAutoUpdateInterval(interval time.Duration) Option

WithAutoUpdateInterval configures how often to automatically update the catalog.

func WithAutoUpdatesDisabled

func WithAutoUpdatesDisabled() Option

WithAutoUpdatesDisabled configures whether automatic updates are disabled.

func WithEmbeddedCatalog

func WithEmbeddedCatalog() Option

WithEmbeddedCatalog configures whether to use an embedded catalog. It defaults to false, but takes precedence over WithLocalPath if set.

func WithLocalPath

func WithLocalPath(path string) Option

WithLocalPath configures the local source to use a specific catalog path.

func WithRemoteServerAPIKey

func WithRemoteServerAPIKey(apiKey string) Option

WithRemoteServerAPIKey configures the remote server API key.

func WithRemoteServerOnly

func WithRemoteServerOnly(url string) Option

WithRemoteServerOnly configures whether to only use the remote server and not hit provider APIs.

func WithRemoteServerURL

func WithRemoteServerURL(url string) Option

WithRemoteServerURL configures the remote server URL.

type Persistence

Persistence handles catalog persistence operations.

type Persistence interface {
    // Save with options
    Save(opts ...save.Option) error
}

type Updater

Updater handles catalog synchronization operations.

type Updater interface {
    // Sync synchronizes the catalog with provider APIs
    Sync(ctx context.Context, opts ...sync.Option) (*sync.Result, error)

    // Update manually triggers a catalog update
    Update(ctx context.Context) error
}

Generated by gomarkdoc