API Documentation

API Documentation#

Overview#

Starmap provides a comprehensive Go API for working with AI model catalogs. This documentation covers the core packages and interfaces.

Core Packages#

Catalogs Package (pkg/catalogs)#

The main interface for working with model catalogs. Provides reading, writing, and querying capabilities.

1import "github.com/agentstation/starmap/pkg/catalogs"

View Go Package Documentation →

Reconcile Package (pkg/reconcile)#

Advanced reconciliation system for merging multiple data sources with field-level authority.

1import "github.com/agentstation/starmap/pkg/reconcile"

View Go Package Documentation →

Sources Package (pkg/sources)#

Interfaces and implementations for various data sources (APIs, files, embedded data).

1import "github.com/agentstation/starmap/pkg/sources"

View Go Package Documentation →

Quick Start#

Reading a Catalog#

 1package main
 2
 3import (
 4    "fmt"
 5    "log"
 6    
 7    "github.com/agentstation/starmap/pkg/catalogs"
 8)
 9
10func main() {
11    // Load catalog from embedded data
12    catalog, err := catalogs.New(catalogs.WithEmbedded())
13    if err != nil {
14        log.Fatal(err)
15    }
16    
17    // List all providers
18    providers := catalog.Providers().List()
19    for _, provider := range providers {
20        fmt.Printf("Provider: %s (%d models)\n", provider.Name, len(provider.Models))
21    }
22    
23    // Get a specific model
24    model, err := catalog.Models().Get("gpt-4")
25    if err != nil {
26        log.Fatal(err)
27    }
28    fmt.Printf("Model: %s\n", model.Name)
29}

Updating from Sources#

1// Sync catalog from provider APIs
2syncer := starmap.NewSyncer(catalog)
3err := syncer.Sync(context.Background(), starmap.SyncOptions{
4    Providers: []string{"openai", "anthropic"},
5})
6if err != nil {
7    log.Fatal(err)
8}

Interfaces#

Reader Interface#

For read-only access to catalogs:

  • Models() - Access model data
  • Providers() - Access provider data
  • Authors() - Access author data

Writer Interface#

For modifying catalogs:

  • Set(item) - Add or update items
  • Delete(id) - Remove items
  • Save() - Persist changes

Syncer Interface#

For synchronizing with external sources:

  • Sync() - Update from sources
  • Reconcile() - Merge multiple sources

Error Handling#

Starmap uses typed errors for better error handling:

1import "github.com/agentstation/starmap/pkg/errors"
2
3if err != nil {
4    if errors.IsNotFound(err) {
5        // Handle 404
6    } else if errors.IsRateLimit(err) {
7        // Handle rate limiting
8    }
9}

Environment Variables#

Configure provider API keys:

1export OPENAI_API_KEY="sk-..."
2export ANTHROPIC_API_KEY="sk-ant-..."
3export GOOGLE_API_KEY="..."

Examples#

For more examples, see:

Package Documentation#

Full Go package documentation is available at:

Support#

For issues or questions: