starmap

README

Starmap ⭐🗺️

A versioned AI model catalog available as a Go package, CLI tool, or HTTP server with REST and SSE.

                             ____  _                                 
                            / ___|| |_ __ _ _ __ _ __ ___   __ _ _ __  
                            \___ \| __/ _` | '__| '_ ` _ \ / _` | '_ \ 
                             ___) | || (_| | |  | | | | | | (_| | |_) |
                            |____/ \__\__,_|_|  |_| |_| |_|\__,_| .__/ 
                                                                |_|    

Installation • Quick Start • API Reference • Contributing

Table of Contents

• Why Starmap?
• Key Features
• Installation
• Quick Start
• Architecture
• Core Concepts
• Project Structure
• Choosing Your Approach
• CLI Usage
• Go Package
• Data Sources
• Model Catalog
• HTTP Server
• Configuration
• Development
• Contributing
• API Reference
• License

Why Starmap?

The Problem

Building AI applications requires accurate information about models across multiple providers, but:

• Fragmented Information: Each provider has different APIs, documentation formats, and update cycles
• Missing Pricing Data: Many providers don't publish pricing through their APIs
• Rapid Changes: New models launch weekly, capabilities change, prices update
• Integration Complexity: Each provider requires custom code to fetch and parse model data
• No Single Source of Truth: Developers must check multiple sources for complete information

The Solution

Starmap provides:

• Unified Catalog: Single interface for all AI model information
• Multi-Source Reconciliation: Combines provider APIs with community data for completeness
• Explicit Synchronization: Refresh from provider APIs and models.dev when your application, CLI, or repository workflow chooses
• Flexible Storage: From in-memory for testing to persistent for production
• Event-Driven Updates: React to model changes in real-time
• Type-Safe Go API: Strongly typed models with comprehensive metadata

Who Uses Starmap?

• AI Application Developers: Discover and compare models for your use case
• Platform Engineers: Maintain accurate model catalogs for your organization
• Tool Builders: Integrate comprehensive model data into your products
• Researchers: Track model capabilities and pricing trends
• Cost Optimizers: Find the best price/performance for your workloads

Key Features

✅ Comprehensive Coverage: 500+ models from 10+ providers ✅ Accurate Pricing: Valid provider-offering prices first, with models.dev fallback ✅ Reactive Distribution: Verified server generations activate from SSE publication hints; source acquisition remains an explicit operation ✅ Flexible Architecture: Simple merging or complex reconciliation ✅ Multiple Interfaces: CLI, Go package, and HTTP server (REST + SSE) ✅ Production Ready: Thread-safe, well-tested, actively maintained

Installation

CLI Tool

# Homebrew (macOS/Linux)
brew install agentstation/tap/starmap

# Or install from source
go install github.com/agentstation/starmap/cmd/starmap@latest

# Verify installation
starmap version

Go Package

The library requires Go 1.25 or newer. Releases are built and verified with Go 1.26.6, while required CI also tests the latest patched Go 1.25 toolchain. Supported library, CLI, server, and remote-consumer compositions require no C toolchain; release archives and containers are built with CGO_ENABLED=0. The external offline composition also verifies a compile-time-pinned catalog artifact and activates it without network access, provider credentials, or acquisition/server dependencies.

# Add to your project
go get github.com/agentstation/starmap

Docker

Starmap release images are built with ko, CGO_ENABLED=0, and a digest-pinned Chainguard static base. Verify and scan the exact image digest, SBOM, and release attestation under your deployment policy.

Quick Start:

# Pull and run the HTTP server
docker run -p 8080:8080 ghcr.io/agentstation/starmap:latest serve --host 0.0.0.0

# Or use docker-compose (recommended)
docker-compose up

Using Docker Compose:

# 1. Copy environment template
cp .env.example .env

# 2. Edit .env with your API keys (optional)
nano .env

# 3. Start the server
docker-compose up -d

# 4. Check health
curl http://localhost:8080/api/v1/health

Available Images:

• ghcr.io/agentstation/starmap:latest - Latest stable release
• ghcr.io/agentstation/starmap:v<version> - Pinned application version
• ghcr.io/agentstation/starmap@sha256:<digest> - Immutable production pin

Supported Platforms:

• linux/amd64 (x86_64)
• linux/arm64 (ARM 64-bit)

See docs/DOCKER.md for detailed deployment guides including Kubernetes, security hardening, and production best practices.

Quick Start

CLI: List Available Models

# List all models
starmap models list

# Filter by provider
starmap models list --provider openai

# Search by capability
starmap models list --capability vision

# Export as JSON
starmap models list --output json > models.json

Unfiltered model rows include provider_id; equal model IDs at different providers remain separate so provider-specific prices and limits are never silently collapsed.

Go Package: Basic Usage

package main

import (
    "fmt"
    "log"
    
    "github.com/agentstation/starmap"
)

func main() {
    // Create starmap with embedded catalog
    sm, err := starmap.New()
    if err != nil {
        log.Fatal(err)
    }
    
    // Get the concrete immutable catalog
    catalog := sm.Catalog()
    
    // Find the canonical GPT-4o definition
    model, err := catalog.FindModel("gpt-4o")
    if err == nil {
        fmt.Printf("Model: %s\n", model.Name)
        fmt.Printf("Model ID: %s\n", model.ID)
    }

    // Provider price and service facts live on offerings.
    offerings, err := catalog.DefinitionOfferings(model.ID)
    if err == nil {
        for _, offering := range offerings {
            fmt.Printf("%s serves %s as %s\n",
                offering.ProviderID, model.ID, offering.ProviderModelID)
        }
    }
}

Sync with Provider APIs

# Set up API keys
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

# Update catalog from all providers
starmap update

# Update specific provider with auto-approve
starmap update openai -y

Architecture

Starmap uses a layered architecture with clean separation of concerns:

• User Interfaces: CLI, Go package, and HTTP server (REST + SSE)
• Core System: Catalog management, reconciliation engine, and event hooks
• Data Sources: Provider APIs, models.dev, embedded catalog, and local files
• Generation Stores: Memory, filesystem, or conditional object storage; embedding applications can inject their own store

For detailed architecture diagrams, design principles, and implementation details, see ARCHITECTURE.md.

Core Concepts

Starmap's core abstractions provide a clean separation of concerns:

1. Catalog

The concrete immutable product for model data access. Advanced producers use a separate builder; ordinary consumers retain and share the catalog safely. See Catalog Package Documentation.

2. CatalogStore

A generation-oriented commit/read/CAS boundary. The same conformance contract covers Starmap's memory, filesystem, and conditional object-storage adapters while retaining old immutable generations. Embedding applications such as Starport may inject a database-backed implementation, but own its driver, schema, migrations, credentials, connection pool, backups, and lifecycle. The exact concurrency, idempotency, failure, rollback, ownership, and error requirements are defined in the Catalog Store Contract. For servers without a durable filesystem, pkg/catalogs/storage/s3 adapts a caller-owned AWS SDK v2 S3 client to the same object-generation contract:

backend, err := s3store.New(callerOwnedS3Client, s3store.Config{
    Bucket: "starmap-catalogs",
})
if err != nil {
    return err
}
store, err := storage.NewObject(backend, "production")

The caller configures and owns the client, endpoint, credentials, transport, retries, and lifecycle. Construction performs no network request, and every write requires an S3-compatible If-None-Match or If-Match conditional write; there is no last-writer-wins fallback.

The standalone starmap serve command uses the CLI's filesystem generation store by default. An embedding server selects storage before it constructs the Starmap client: use storage.NewFilesystem for a persistent local path, or compose s3store.New with storage.NewObject for an S3-compatible bucket, then inject the selected store through starmap.WithCatalogStore. Storage mode, paths, bucket, prefix, client, credentials, and lifecycle remain deployment configuration; server.New receives the already-constructed client and does not open storage.

When a client starts with a configured store, it validates and publishes that store's current generation before returning from starmap.New; an empty store uses either the exact configured human workspace or the verified embedded bootstrap until its first successful commit.

Validated generations use a deterministic archive and detached in-toto statement for release/hosted distribution. See the Catalog Artifact Format.

3. Provider Offering

The provider-scoped service contract for a model definition. Its key combines the provider ID with the provider's exact opaque model ID, so equal model IDs at different providers retain independent pricing, limits, availability, regions, endpoint behavior, lifecycle, modes, and request overrides.

4. Source

Abstraction for fetching data from external systems (provider APIs, models.dev, local files). Each implements a common interface for consistent data access.

5. Reconciliation

The acquisition pipeline combines source observations with field-level authority, provenance tracking, and conflict resolution before publishing one validated generation. Consumers compose this through acquisition.Syncer, while the reconciliation engine remains an internal implementation detail.

Provider adapters project only directly observed model facts and catalog- declared mappings. They do not infer capabilities or authors from model-family names. An offering without a reviewed canonical model link stays out of the catalog and becomes a durable review candidate in the generation manifest. The candidate retains the exact provider model ID and its source revision and evidence checksum.

6. Model Definition

The canonical provider-independent model record: authorship, lineage, weights/architecture, release metadata, and intrinsic capabilities. Provider pricing, limits, availability, regions, lifecycle, modes, endpoints, and request behavior belong to provider offerings. See pkg/catalogs/README.md for the schema reference.

Add a provider with YAML

A provider needs no Go change when it uses a compiled catalog transport and authentication primitive. Its response fields must also fit that transport's typed source vocabulary.

1. Add the canonical author to internal/embedded/catalog/authors.yaml when it does not exist.
2. Add intrinsic model facts to internal/embedded/catalog/authors/<author>/models/<slug>.yaml.
3. Add the provider record to internal/embedded/catalog/providers.yaml. Declare credentials, the catalog endpoint, inference endpoints, and status sources there.
4. Add each reviewed offering below internal/embedded/catalog/providers/<provider>/models/. Preserve the provider's exact id. Set model: <author>/<slug> explicitly.
5. Run make validate.
6. Run make update-catalog-provider PROVIDER=<provider> when the provider API is available.
7. Run make verify before publication.

field_mappings select typed wire fields and canonical destinations. The first present source for one destination wins in YAML order. OpenAI-compatible sources include context_window and max_completion_tokens. Their canonical destinations are limits.context_window and limits.output_tokens.

author_mapping selects a transport-supported author field and maps exact, case-insensitive, or glob values to an existing canonical author. OpenAI- compatible acquisition supports id and owned_by. Google acquisition supports publisher where its transport contract declares it.

capability_mappings use exact typed provider predicates. Each mapping cites an HTTPS provider contract and names each entailed canonical target. A mapping can use conflict, first-known, any, or all combination behavior. Model IDs, author names, family names, and free text cannot create capability facts.

A known offering publishes only when its exact provider ID has an explicit canonical model link. An unknown discovered ID stays out of the catalog and becomes a durable review candidate. Add its authored model and offering record before the next publication. The generator derives the endpoint projections. Do not use them as an authoring source.

For detailed component design and interaction patterns, see ARCHITECTURE.md § System Components.

Project Structure

Starmap follows Go best practices with clear package separation:

• pkg/ - Focused public contracts (catalogs, storage, artifact, remote protocol, sources, errors, etc.)
• internal/ - Internal implementations (reconciliation, CLI, providers, embedded data, transport)
• cmd/starmap/ - CLI application

See CONTRIBUTING.md § Project Structure for detailed directory layout and dependency rules.

Choosing Your Approach

Starmap provides two composition levels:

Use Catalog Package (Simple) When:

• ✅ Constructing or reading one provider-YAML catalog
• ✅ Combining two provider responses
• ✅ Testing with mock data
• ✅ Building simple tools

Use acquisition.Syncer When:

• ✅ Syncing with multiple provider APIs
• ✅ Integrating models.dev for pricing
• ✅ Importing a publisher-verified portable catalog release
• ✅ Different sources own different fields
• ✅ Need audit trail of data sources
• ✅ Building production systems

For architecture details and the internal reconciliation algorithm, see ARCHITECTURE.md § Reconciliation System.

CLI Usage

Core Commands

# Discovery
starmap models list              # List all models
starmap providers                # List all providers
starmap authors                  # List all authors

# Model field history
starmap models history gpt-4o                    # View field provenance
starmap models history shared --provider=openrouter # Select a provider offering
starmap models history gpt-4o --fields=Name      # Filter to specific field
starmap models history gpt-4o --fields=Name,ID   # Multiple fields

# Update catalog
starmap update                  # Update all providers
starmap update openai           # Update specific provider
starmap update --dry-run        # Preview changes
starmap migrate catalog         # Explicitly migrate the former local store layout

# Development
starmap validate                # Validate configurations
starmap deps check              # Check dependency status
starmap completion bash         # Generate shell completion

Advanced Update Workflows

# Development: Use a custom human workspace
starmap update groq --catalog-path ./catalog --dry-run

# Production: Fresh update with auto-approval
starmap update --force -y

# Specific sources only
starmap update --source models.dev

# Reload semantic edits from the human workspace; no filesystem watcher runs
starmap update --source local

# Reproducible Git verification requires an exact commit
starmap update --source models.dev-git --models-dev-git-commit <40-or-64-hex-commit>

Dependency Management

Some data sources require external tools. Starmap handles missing dependencies gracefully:

# Interactive (default) - Prompts to install or skip
starmap update

# CI/CD - Skip sources with missing dependencies
starmap update --skip-dep-prompts

# Strict mode - Require every configured source to be healthy and nonempty
starmap update --require-all-sources --skip-dep-prompts

# Auto-install - Install dependencies automatically
starmap update --auto-install-deps

The starmap update command owns the interactive prompt adapter. Go library, server, repository-job, and other non-CLI sync calls never read stdin: they skip an optional source with missing dependencies and return a typed error for a required source unless an explicit noninteractive dependency policy is configured.

Available Flags:

• --auto-install-deps - Automatically install missing dependencies
• --skip-dep-prompts - Skip sources with missing dependencies without prompting
• --require-all-sources - Fail before reconciliation unless every configured source is available, complete, successful, and returns at least one model (CI/CD mode)

Common Scenario: The models_dev_git source requires bun for building. If missing, Starmap offers to install it or falls back to models_dev_http which provides the same data without dependencies.

Checking Dependencies

Use starmap deps check to verify dependency status before running updates:

# Check all dependencies
starmap deps check

# JSON output for tooling
starmap deps check --output json

# YAML output
starmap deps check --output yaml

The command shows:

• ✅ Available dependencies with version and path
• ❌ Missing dependencies with installation instructions
• ℹ️ Sources that don't require any dependencies

Example output:

Dependency Status:

┌────────────────────────────┬────────────────────────┬──────────────────┬─────────┬───────────────────────┐
│           SOURCE           │       DEPENDENCY       │      STATUS      │ VERSION │         PATH          │
├────────────────────────────┼────────────────────────┼──────────────────┼─────────┼───────────────────────┤
│ embedded_catalog           │ -                      │ ✅ None required │ -       │ -                     │
│ local_catalog (optional)   │ -                      │ ✅ None required │ -       │ -                     │
│ providers                  │ -                      │ ✅ None required │ -       │ -                     │
│ models_dev_git (optional)  │ Bun JavaScript runtime │ ✅ Available     │ 1.2.21  │ /opt/homebrew/bin/bun │
│                            │ Git version control    │ ✅ Available     │ 2.51.0  │ /opt/homebrew/bin/git │
│ models_dev_http (optional) │ -                      │ ✅ None required │ -       │ -                     │
└────────────────────────────┴────────────────────────┴──────────────────┴─────────┴───────────────────────┘

Additional Information:

Bun JavaScript runtime (models_dev_git):
  Description: Fast JavaScript runtime for building models.dev data
  Why needed:  Builds api.json from models.dev TypeScript source

Summary:
┌────────────────────────────────┬───────┐
│             STATUS             │ COUNT │
├────────────────────────────────┼───────┤
│ ✅ Available                   │ 2     │
│ ℹ️ Sources without dependencies │ 3     │
└────────────────────────────────┴───────┘
✅ All required dependencies are available.

Environment Setup

# Required for provider syncing
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...
export GROQ_API_KEY=...
export DEEPSEEK_API_KEY=...
export CEREBRAS_API_KEY=...
export HETZNER_API_KEY=...
export DASHSCOPE_API_KEY=...
export FIREWORKS_API_KEY=...

# Optional for DeepInfra catalog fetch; required for inference calls
export DEEPINFRA_TOKEN=...

# Optional for Alibaba Cloud Model Studio regions that use workspace domains
export ALIBABA_MODEL_STUDIO_BASE_URL=https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

# Optional for Google Vertex
export GOOGLE_VERTEX_PROJECT=my-project
export GOOGLE_VERTEX_LOCATION=us-central1

Go Package

Installation and Setup

import (
    "github.com/agentstation/starmap"
    "github.com/agentstation/starmap/pkg/catalogs"
)

Basic Usage Patterns

Simple Catalog Access

// Default embedded catalog; construction starts no background work.
sm, err := starmap.New()
if err != nil {
    return err
}
catalog := sm.Catalog()

// Query canonical model definitions
model, err := catalog.FindModel("gpt-4o")
if err != nil {
    return err
}
fmt.Printf("Model: %s\n", model.Name)

// Provider-specific facts remain exact and separately addressable. Provider
// identity is independent from the author/lab that created the model.
offerings, err := catalog.DefinitionOfferings(model.ID)
if err != nil {
    return err
}
for _, offering := range offerings {
    if offering.Pricing != nil {
        fmt.Printf("%s input price: %v\n",
            offering.ProviderID, offering.Pricing.Tokens.Input.Per1M)
    }
}

New is the convenient read-only constructor and uses a background context. When construction reads a configured generation store, use NewContext so the caller owns cancellation and deadlines:

sm, err := starmap.NewContext(ctx,
    starmap.WithCatalogStore(store),
    starmap.WithCatalogPath("./catalog"),
)
if err != nil {
    return err
}
catalog := sm.Catalog() // non-nil after successful construction

Calling Catalog on a nil *starmap.Client returns nil. For every successfully constructed client the accessor is non-failing, non-nil, O(1), allocation-free, and safe to retain across goroutines.

Event-Driven Updates

// React to catalog changes
sm.OnModelAdded(func(model catalogs.Model) {
    log.Printf("New model: %s", model.ID)
})

sm.OnModelUpdated(func(old, new catalogs.Model) {
    if old.Pricing.Input != new.Pricing.Input {
        log.Printf("Price changed for %s", new.ID)
    }
})

// Durable publication callbacks run asynchronously after Store.Commit.
sm.OnCatalogPublished(func(event starmap.CatalogPublishedEvent) error {
    log.Printf("catalog generation %s from sync %s", event.GenerationID, event.SyncRunID)
    return nil
})

stats := sm.HookStats() // failures, panics, coalesced generations, and callback latency

Generation-store CAS is the durable commit point. The immutable catalog, generation identity, and sequence become visible atomically before callbacks begin. Callback delivery never lets a later generation overtake an earlier one. If callbacks lag, Starmap keeps the running generation plus the newest pending generation; skipped intermediate sequences are observable through the event sequence and HookStats().Coalesced.

Advanced Catalog Construction

// Builders are for custom source/plugin authors and update pipelines.
builder, err := catalogs.New(
    catalogs.WithPath("./my-catalog"),
)
if err != nil {
    return err
}
catalog, err := builder.Build()
if err != nil {
    return err
}

The human workspace keeps canonical authored facts and provider-serving facts readable but separate:

# authors/moonshot-ai/models/kimi-k2.5.yaml
id: kimi-k2.5
name: Kimi K2.5
authors:
  - id: moonshot-ai
    name: Moonshot AI

# providers/alibaba/models/kimi-k2.5.yaml
id: kimi-k2.5
model: moonshot-ai/kimi-k2.5
name: Kimi K2.5
pricing:
  currency: USD
  tokens:
    input:
      per_1m: 0.60

Any number of providers may link to the same author/slug; a provider may also serve models from many unrelated authors. Starmap generates endpoints.yaml from these validated links. That file is a digest-bound inspection/export projection, not an editable source of truth.

Syncing with Provider APIs

// Non-dry mutation requires an explicit writable generation store.
store, err := storage.NewFilesystem("./state/catalog")
if err != nil {
    return err
}
sm, err := starmap.New(
    starmap.WithCatalogStore(store),
    starmap.WithCatalogPath("./catalog"),
)
if err != nil {
    return err
}
syncer, err := acquisition.New(sm)
if err != nil {
    return err
}

// Sync a selected provider API.
result, err := syncer.Sync(ctx,
    sync.WithProvider("openai"),
    sync.WithDryRun(false),
)

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Added: %d models\n", result.Added)
fmt.Printf("Updated: %d models\n", result.Updated)
fmt.Printf("Removed: %d models\n", result.Removed)

Importing a Verified Catalog Release

An importer supplies the three immutable release assets and a channel-specific artifact.PublisherVerifier. For GitHub Releases, that verifier should require the exact agentstation/starmap repository and catalog generation workflow identity. Starmap verifies all trust inputs before mutation, reconciles release facts below human workspace evidence, and retains the prior generation for rollback:

result, err := syncer.ImportRelease(ctx, artifact.Release{
    Archive:     archive,
    Checksum:    checksum,
    Attestation: statement,
}, publisherVerifier)
if err != nil {
    return err
}
if result.Publication.Published {
    fmt.Println(result.Publication.GenerationID)
}

The deterministic detached statement authenticates content structure, not publisher identity. Credentials, network clients, and trust policy remain caller-owned.

Advanced Patterns

Explicit Updates with Custom Logic

publication, err := sm.Update(ctx, func(
    ctx context.Context,
    current *catalogs.Catalog,
) (*starmap.Candidate, error) {
    builder, err := catalogs.NewBuilderFrom(current)
    if err != nil {
        return nil, err
    }
    // Apply custom observations to builder while honoring ctx.
    updated, err := builder.Build()
    if err != nil {
        return nil, err
    }
    return starmap.NewCandidate(updated, starmap.CandidateEvidence{})
})
if err != nil {
    return err
}
if publication.Published {
    log.Printf("published catalog generation %s", publication.GenerationID)
}

Filtering and Querying

// Definitions describe the model; offerings preserve each provider's exact
// service facts. Equal model IDs at two providers never overwrite each other.
for _, definition := range catalog.Definitions() {
    if definition.Capabilities.Features == nil ||
        !slices.Contains(definition.Capabilities.Features.Modalities.Input, "image") {
        continue
    }

    offerings, err := catalog.ProviderOfferings("openai")
    if err != nil {
        return err
    }
    for _, offering := range offerings {
        if offering.DefinitionID == definition.ID {
            fmt.Printf("%s is offered by %s\n", definition.Name, offering.ProviderID)
        }
    }
}

Data Sources

Starmap combines data from multiple sources:

• Provider APIs: Real-time model availability (OpenAI, Anthropic, Google, Alibaba Cloud, Fireworks AI, DeepInfra, etc.)
• models.dev: Community-verified pricing and metadata (models.dev)
• Embedded Catalog: Baseline data shipped with starmap
• Local Files: Human authored-model and provider-serving YAML plus manual fallback data; generated endpoints.yaml is not an authority

For detailed source hierarchy, authority rules, and how sources work together, see ARCHITECTURE.md § Data Sources.

Model Catalog

Starmap includes 500+ models from 10+ providers (OpenAI, Anthropic, Google, Groq, DeepSeek, Cerebras, Hetzner, Alibaba Cloud, Fireworks AI, DeepInfra, and more). Each package has detailed documentation in its README.

Catalog reads keep natural Go scalar fields. When an algorithm needs to distinguish an unreported value from an explicit zero, use the presence API:

if model.Features != nil {
    supported, presence := model.Features.Support(catalogs.ModelFeatureToolCalls)
    switch presence {
    case catalogs.ValueKnown:
        fmt.Printf("tool calls reported: %t\n", supported)
    case catalogs.ValueUnknown:
        fmt.Println("tool call support explicitly unknown")
    case catalogs.ValueMissing:
        fmt.Println("source did not report tool call support")
    }
}

For source/plugin authors, non-zero literals need no extra ceremony. Use SetSupport, ModelLimits.Set, SetDescription, or SetOpenWeights when a reported false, 0, or "" must remain distinct from an omitted field. Human YAML uses the same intuitive contract: omitted means missing, null means unknown, and a zero-valued scalar is explicit.

HTTP Server

Start a production-ready REST API server for programmatic catalog access:

# Start on default port 8080
starmap serve

# Custom configuration
starmap serve --port 3000 --cors --auth --rate-limit 100

# With specific CORS origins
starmap serve --cors-origins "https://example.com,https://app.example.com"

Go programs can embed the same server directly. Construction starts no listener or background goroutine; Serve owns serving on the caller-provided listener, and Shutdown drains HTTP before stopping server services:

sm, err := starmap.New()
if err != nil {
    return err
}
srv, err := server.New(sm, server.DefaultConfig())
if err != nil {
    return err
}
listener, err := net.Listen("tcp", "127.0.0.1:8080")
if err != nil {
    return err
}
go func() {
    if err := srv.Serve(listener); err != nil {
        log.Printf("starmap server: %v", err)
    }
}()
defer srv.Shutdown(shutdownCtx)

The public server is read-only by default and does not import provider clients or acquisition implementations. To expose POST /api/v1/update, explicitly compose an acquisition.Syncer and pass server.WithSyncer(syncer). This keeps ordinary server embedding independent from provider credentials and cloud SDKs.

Features:

• RESTful API: Models, providers, search endpoints with filtering
• OpenRouter catalog compatibility: Exact model-by-author/slug and model-endpoints discovery routes over the same immutable catalog
• Reactive Updates: SSE (/api/v1/updates/stream) emits heartbeat comments and one post-commit catalog.published hint containing generation ID and sequence
• Performance: Generation-scoped in-memory caching, deterministic query sorting, rate limiting (per-IP)
• Security: Optional API key authentication, CORS support
• Monitoring: Health checks (/health, /api/v1/ready), operational catalog/publication/stream health (/api/v1/stats and srv.Health()), and metrics endpoint
• Publication identity: Catalog responses and real-time publication events carry the durable generation identity
• Documentation: OpenAPI 3.1 specs at /api/v1/openapi.json

API Endpoints:

# Models
GET  /api/v1/models              # List with filtering
GET  /api/v1/models/{id}         # Get specific model
POST /api/v1/models/search       # Advanced search

# OpenRouter-compatible catalog discovery
GET  /api/v1/model/{author}/{slug}
GET  /api/v1/models/{author}/{slug}/endpoints

# Providers
GET  /api/v1/providers           # List providers
GET  /api/v1/providers/{id}      # Get specific provider
GET  /api/v1/providers/{id}/models  # Get provider's models

# Remote generation consumption
GET  /api/v1/catalog/manifest
GET  /api/v1/catalog/generations/{generation_id}/manifest
GET  /api/v1/catalog/generations/{generation_id}/payload
GET  /api/v1/updates/stream      # Heartbeat-enabled publication hints

# Admin
POST /api/v1/update              # Trigger catalog sync
GET  /api/v1/stats               # Catalog statistics

# Health
GET  /health                     # Liveness probe
GET  /api/v1/ready               # Readiness check

The OpenRouter-compatible adapter implements OpenRouter's documented model-by-slug and model-endpoints contracts. It resolves canonical author IDs, author aliases, known catalog model aliases, and explicitly configured mode suffixes such as :free. It returns authored identity and intrinsic facts from the model definition, then joins every eligible provider offering at response time. Endpoint rows therefore retain the serving provider and its exact opaque model ID even when that provider serves models from unrelated labs. The model summary uses the least expensive eligible USD provider price deterministically; each endpoint retains its own provider price and limits in OpenRouter's documented string units.

The adapter does not read generated endpoints.yaml and does not create another catalog authority. That file remains the digest-bound, human-inspectable projection of the same definition/offering join. Runtime latency, throughput, and uptime fields are omitted because Starmap does not currently compose a provider-performance telemetry producer; catalog freshness and SSE health are not substitutes for provider performance. Optional server authentication still governs these routes, with OpenRouter-shaped numeric 401 error envelopes. Model detail links honor the server's configured path prefix.

Go consumers can opt into reactive remote catalogs without adding network behavior to the root package:

store, err := storage.NewFilesystem("/var/lib/my-service/starmap")
if err != nil {
    return err
}
subscriber, err := remote.NewContext(ctx, remote.Config{
    BaseURL:      "https://starmap.example.com/api/v1",
    CatalogStore: store,
})
if err != nil {
    return err
}
if err := subscriber.Start(ctx); err != nil {
    return err
}
defer subscriber.Close()

state := subscriber.State()
model, err := state.Catalog.FindModel("gpt-4o")

health := subscriber.Health()
log.Printf(
    "stream=%s generation=%s age=%ds retries=%d",
    health.StreamState,
    health.ActiveGenerationID,
    health.CatalogAgeSeconds,
    health.Retries,
)

Each subscriber requires a CatalogStore that the caller owns. Construction loads the verified current generation before remote work. An optional PinnedBootstrap seeds only an empty store. A valid durable current generation always wins. Corrupt or unavailable store state causes construction to fail. State returns one atomic catalog, generation ID, payload checksum, timestamp, and sequence.

SSE events are generation hints, not catalog payloads. Reconnect always fetches and verifies current state. Thus, dropped or replayed events cannot permanently stale or partially mutate the catalog. A newer identity for the same payload advances the durable and atomic identity. It emits one generation event without replacing the catalog pointer or publishing model-change hooks. Comment heartbeats reset the stream-liveness deadline without triggering a fetch.

If the initial remote fetch or stream has a nonterminal failure, Start keeps the verified local state. It then starts bounded streaming recovery. HTTP 401 and 403 remain terminal. The caller context owns initial fetch, streaming, retry, and activation. Close cancels and joins that lifecycle within a bounded timeout.

Polling is off by default. Streaming reconnect remains active. Deployments can enable bounded conditional manifest polling during a long SSE outage:

PollingFallback: &remote.PollingFallbackPolicy{
    AfterFailures: 3,
    Interval:      30 * time.Second,
},

The subscriber sends conditional current-manifest requests only after that stream-failure threshold. It never polls beside a healthy stream, consumes at a rate bounded by the configured interval, and exposes the current mode and cumulative counters through PollingFallbackStatus(). Authentication failures (HTTP 401 or 403) are terminal for the active lifecycle: they do not retry or enter polling fallback. Construct a new subscriber after credentials or access policy have been corrected.

subscriber.Health() reports stream state, last heartbeat, last publication event, last successful catch-up, active generation age, retry count, fallback status, and a structured secret-free last error. Heartbeats establish transport liveness only; they never change the active generation timestamp or catalog age. The publisher exposes the matching server-side view through srv.Health() and /api/v1/stats, including callback coalescing and SSE backpressure/write termination counters.

BaseURL is the trusted publisher origin. Non-loopback servers require HTTPS with a verified certificate chain, and redirects cannot change origin. Plain HTTP is accepted only for local loopback embedding and tests.

Configuration Flags:

• --port: Server port (default: 8080)
• --host: Bind address (default: localhost)
• --cors: Enable CORS for all origins
• --cors-origins: Specific CORS origins (comma-separated)
• --auth: Enable API key authentication
• --rate-limit: Requests per minute per IP (default: 100)
• --cache-ttl: Cache TTL in seconds (default: 300)
• --sse-heartbeat-interval: Flushed comment heartbeat interval (default: 20s)
• --sse-write-timeout: Per-frame SSE write and flush deadline (default: 10s)

Environment Variables:

HTTP_PORT=8080
HTTP_HOST=0.0.0.0
API_KEY=changeme  # If --auth enabled

For the embeddable API, see server/README.md.

Configuration

Environment Variables

Provider YAML declares the conventional environment names for each credential field. Starmap checks those names in their declared order. If no conventional name contains a value, Starmap checks the derived STARMAP_<PROVIDER_ID>_<FIELD_ID> name. For example:

export OPENAI_API_KEY=sk-...

# Used only when OPENAI_API_KEY is not set.
export STARMAP_OPENAI_API_KEY=sk-...

# Starmap logging
export LOG_LEVEL=info
export LOG_FORMAT=auto
export LOG_OUTPUT=stderr

# Optional readiness budgets while the embedded offline bootstrap is active
export EMBEDDED_BOOTSTRAP_MAX_AGE=168h
export EMBEDDED_BOOTSTRAP_MAX_SIZE_BYTES=16777216

Starmap selects the first nonempty environment value. Resolution fails if that value does not satisfy the catalog field contract. Starmap does not try a later name. The resolver can use a Google, Azure, or AWS default credential chain after catalog-declared ambient fields are absent.

Select a non-default configuration file with starmap --config /path/to/config.yaml <command>. Set catalog_path in that file or use CATALOG_PATH to select the human-editable provider YAML workspace.

Authentication Management

These commands check catalog-acquisition authentication. Starmap uses these credentials only to contact providers and build catalog observations. It does not publish the credentials in a catalog generation and it does not define how an inference gateway stores or applies inference credentials.

Check and verify your acquisition authentication setup:

# Check authentication status for all providers
starmap providers

# Test credentials by making test API calls
starmap providers --test

# Test specific provider
starmap providers openai --test

# JSON output for automation
starmap providers --output json

# Manage Google Cloud authentication
starmap auth gcloud

The providers command shows:

• Configured providers
• Acquisition authentication method (API key or cloud chain)
• Missing credentials with setup instructions
• Provider details (name, ID, location, type, models count)

Provider records separately contain inference service facts, such as base URLs, operation paths, offering capabilities, and status-page metadata. A consumer such as Starport owns gateway and provider inference authentication. It must not reuse Starmap's catalog-acquisition credentials for inference.

Configuration File

Local storage uses separate lifecycle roots:

~/.starmap/
├── catalog/          # one human-editable provider-YAML workspace
├── state/catalog/    # machine-owned immutable generation store
│   ├── current
│   └── generations/
├── cache/
├── logs/
├── sources/
└── config.yaml

The machine state directory is passive until the first commit. The catalog workspace is the only human model representation and is both the local observation and the post-commit YAML projection. Starmap rejects overlapping workspace/state roots and rejects models.dev cache or checkout roots that contain, equal, or sit beneath the workspace before reading or writing it. Every authored and provider model YAML exposes the same complete Boolean capability checklist: unobserved capabilities are displayed as false, explicit uncertainty remains null, and missing numeric limits are not invented as zero. This keeps hand editing discoverable while provenance and source authority still allow a later provider or upstream observation to replace untouched projection defaults. Machine-store reads and commits reject symbolic-link substitutions for the store root and its owned lock, current pointer, generation, manifest, and payload entries. Deployments must protect the parent data path from a hostile same-UID actor. Atomic projection uses hidden sibling staging and a hidden sibling generation/digest marker; neither is loaded as provider configuration, and normal completion removes all staging. A sibling advisory writer lock serializes projection and repair across processes; contention returns a typed conflict while readers continue to observe one complete old or new tree. The lock file carries no catalog data and an exited process cannot leave it held. A pre-plan generation-store layout found at ~/.starmap/catalog fails with a typed migration error before mutation. Migrate that layout explicitly:

starmap migrate catalog

The command locks and validates the complete old store, including every retained generation and its schema compatibility, before moving anything. It then relocates the machine store to ~/.starmap/state/catalog and projects the current generation back to ~/.starmap/catalog as provider YAML. Stop every older Starmap process that uses this path before migration and do not restart it afterward; older binaries do not understand the path's new meaning. A normal failure restores the original layout. If another actor recreates the vacated path, rollback preserves both it and the relocated store and returns a typed conflict rather than deleting either. If the process exits after the atomic store move, the next startup reads the exact relocated current generation and repairs the missing YAML projection without publishing a new generation.

Read-only construction uses the verified embedded catalog entirely in memory and creates no workspace. The first explicit update observes that catalog as embedded_catalog, commits one immutable generation even when its facts are unchanged, and then atomically creates the complete provider-YAML workspace. An absent path is never reported as local_catalog; local evidence begins only after a real human workspace exists.

Later explicit updates load the human workspace and the running binary's verified embedded revision as separate observations. Unchanged generated fields can advance with the embedded revision, embedded data can fill missing fields, and semantic human edits remain local evidence. Provider acquisition uses a derived configuration view that keeps human connection settings while adding providers introduced by the new embedded revision.

Starmap never watches the workspace implicitly. A running client retains its current immutable catalog until the caller invokes Sync(ctx, sync.WithSources(sources.LocalCatalogID)); the CLI equivalent is starmap update --source local. One semantic change publishes one generation. An unchanged or formatting-only reload publishes none.

Rollback reactivates a retained immutable generation through the same generation-store compare-and-swap used by normal publication, then atomically reproduces that generation's provider YAML and provenance:

result, err := sm.Rollback(ctx, generationID)
if err != nil {
    return err
}
if result.Projection != nil && result.Projection.Status == sync.ProjectionStatusPendingRepair {
    // The generation is already active; preserve a concurrent human edit and
    // surface that the workspace still needs repair.
}

The generation payload digest and workspace semantic digest are intentionally separate: derived read views live only in the immutable catalog. Repeating a rollback to the current durable generation does not emit another publication.

# ~/.starmap/config.yaml
catalog_path: ~/.starmap/catalog
embedded_bootstrap_max_age: 168h
embedded_bootstrap_max_size_bytes: 16777216

credential_sources:
  openai:
    api-key:
      reference: file:/run/secrets/openai-api-key
      fallback_ambient: false

credential_sources keys must be canonical provider IDs and catalog-declared field IDs. An explicit reference runs before ambient discovery. fallback_ambient: true permits ambient discovery only when the explicit source reports not_configured. Invalid, denied, unavailable, timeout, and cancellation failures are terminal.

Use env:NAME when one operator-selected environment variable must override the catalog's conventional names. This example selects TEAM_OPENAI_API_KEY even when OPENAI_API_KEY is also present:

credential_sources:
  openai:
    api-key:
      reference: env:TEAM_OPENAI_API_KEY
      fallback_ambient: false

The selected value must satisfy the catalog field contract. Starmap does not continue to another environment name after it selects an invalid value. Set fallback_ambient: true only if an absent explicit environment value can use the conventional discovery order.

Core references are env:NAME and file:/absolute/path. The complete grammar is backend:resource?version=VERSION#field. The environment and file sources reject version and field.

Starmap also includes these direct read sources:

Backend	Reference resource	Authentication
gcp-secret-manager	projects/PROJECT/secrets/SECRET or the regional form	Application Default Credentials
azure-key-vault	https://VAULT_HOST/secrets/SECRET	DefaultAzureCredential
aws-secrets-manager	A secret name or ARN	The AWS default credential chain
vault	MOUNT/PATH for a KV v2 secret	The Vault client environment
openbao	MOUNT/PATH for a KV v2 secret	The OpenBao client environment

The optional version selects a provider version. Each source selects the latest version when version is absent. For Google Cloud, Azure, and AWS, field selects one exact top-level JSON string. Without field, these sources preserve the complete scalar payload. For Vault and OpenBao, field selects one exact string value. A reference without field requires exactly one string value.

Backend authentication values do not belong in a reference. Google Cloud uses Application Default Credentials. Azure uses DefaultAzureCredential. AWS uses its default configuration and credential chain. Vault uses its standard client environment, including VAULT_ADDR, VAULT_TOKEN, and VAULT_NAMESPACE. OpenBao uses its standard client environment, including BAO_ADDR, BAO_TOKEN, and BAO_NAMESPACE.

Each direct source creates its official client on resolution and closes its owned network resources after the read.

Use a regular, absolute credential file that is nonempty and no larger than 1 MiB. Starmap preserves every byte. It does not trim a trailing newline. If the provider rejects a newline, create the file without one.

The process-owned resolver reads static files on each resolution and detects in-place writes, atomic replacement, symlink target swaps, projected-volume replacement, and agent rerender. Detection does not depend on modification time alone. The resolver caches renewable cloud material until its refresh time. Concurrent refreshes share one source operation. The resolver exposes opaque material versions that contain no secret digest or source path.

External secret CLIs can inject the catalog-declared conventional environment names into one Starmap process. Authenticate and select the external project or environment first. Then use one of these forms:

# Doppler
doppler run -- starmap update

# 1Password: .env.starmap contains NAME=op://vault/item/field references
op run --env-file="./.env.starmap" -- starmap update

# Infisical
infisical run -- starmap update

See the official command references for Doppler, 1Password, and Infisical. Environment values belong to the child process. Start a new update process to receive a changed value.

Provider connection and credential metadata live with each human-readable provider record. Credential values remain deployment state in environment variables, explicit references, or cloud default chains. Embedding programs can inject a deployment-owned sources.ProviderCredentialResolver with acquisition.WithCredentialResolver. Acquisition source selection and approval are operation inputs (starmap update flags or sync.Option values), not long-lived configuration that can silently start work. Logging uses the explicit LOG_LEVEL, LOG_FORMAT, and LOG_OUTPUT environment variables or the corresponding CLI flags where exposed.

Development

To contribute or develop locally:

git clone https://github.com/agentstation/starmap.git
cd starmap
make all

See CONTRIBUTING.md for complete development setup, testing guidelines, and contribution process.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup and workflow
• How to add new providers
• Testing requirements
• Pull request process
• Code guidelines

Quick links:

• Report Bug
• Request Feature
• Contributing Guide

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

The AGPL ensures that:

• Source code remains open for any network use
• Modifications must be shared with users
• The community benefits from all improvements

See LICENSE file for full details.

---

Built with ❤️ by the Starmap Community

Report Bug • Request Feature • Join Discord

---

API Reference

For complete API documentation including all types, interfaces, and functions, see API.md.

Quick links:

• Client Interface
• Catalog Operations
• Sync and Updates
• Event Hooks
• Configuration Options

Documentation

Overview

Package starmap provides the small, provider-independent entry point for the Starmap AI model catalog system.

Starmap wraps the underlying catalog system with additional features including: - Event hooks for model changes (added, updated, removed) - Thread-safe access to an immutable canonical catalog - Explicit, serialized publication of complete catalog generations - Flexible configuration through functional options

Example usage:

// Create a starmap instance with default settings
sm, err := starmap.New()
if err != nil {
    log.Fatal(err)
}
// Register event hooks
sm.OnModelAdded(func(model catalogs.Model) {
    log.Printf("New model: %s", model.ID)
})

// Get the current immutable catalog
catalog := sm.Catalog()

model, err := catalog.FindModel("gpt-4o")
if err != nil {
    log.Fatal(err)
}

// Provider acquisition is an explicit opt-in composition.
syncer, err := acquisition.New(sm)
if err != nil {
    log.Fatal(err)
}
result, err := syncer.Sync(ctx,
    sync.WithProvider("openai"),
    sync.WithDryRun(true),
)
if err != nil {
    log.Fatal(err)
}

Package starmap provides immutable AI model catalog reads, explicit generation publication, event hooks, and caller-selected generation storage.

Index

• Constants
• func EmbeddedBuilder() (*catalogs.Builder, error)
• type Candidate
  • func NewCandidate(catalog *catalogs.Catalog, evidence CandidateEvidence) (*Candidate, error)
• type CandidateEvidence
• type CatalogPublishedEvent
• type CatalogPublishedHook
• type CatalogReadiness
• type CatalogState
• type Client
  • func New(opts ...Option) (*Client, error)
  • func NewContext(ctx context.Context, opts ...Option) (*Client, error)
  • func (c *Client) Activate(ctx context.Context, generation catalogs.Generation) (Publication, error)
  • func (c *Client) Catalog() *catalogs.Catalog
  • func (c *Client) CurrentCatalogState() CatalogState
  • func (c *Client) CurrentGeneration(ctx context.Context) (catalogs.Generation, error)
  • func (c *Client) CurrentGenerationID() string
  • func (c *Client) Generation(ctx context.Context, id string) (catalogs.Generation, error)
  • func (c *Client) HookStats() HookDeliveryStats
  • func (c *Client) OnCatalogPublished(fn CatalogPublishedHook)
  • func (c *Client) OnModelAdded(fn ModelAddedHook)
  • func (c *Client) OnModelRemoved(fn ModelRemovedHook)
  • func (c *Client) OnModelUpdated(fn ModelUpdatedHook)
  • func (c *Client) Readiness() CatalogReadiness
  • func (c *Client) Rollback(ctx context.Context, generationID string) (*RollbackResult, error)
  • func (c *Client) Save() error
  • func (c *Client) SaveTo(path string) error
  • func (c *Client) Update(ctx context.Context, update UpdateFunc) (Publication, error)
  • func (c *Client) WorkspacePath() string
• type EmbeddedBootstrapInfo
• type HookDeliveryStats
• type ModelAddedHook
• type ModelRemovedHook
• type ModelUpdatedHook
• type Option
  • func WithCatalogPath(path string) Option
  • func WithCatalogStore(store storage.Store) Option
  • func WithEmbeddedBootstrapMaxAge(maxAge time.Duration) Option
  • func WithEmbeddedBootstrapMaxSizeBytes(maxSizeBytes int64) Option
• type Publication
• type ReadinessIssue
• type RollbackResult
• type UpdateFunc

Constants

const (
	// ReadinessIssueCatalogUnavailable means no active immutable catalog exists.
	ReadinessIssueCatalogUnavailable = "catalog_unavailable"
	// ReadinessIssueEmbeddedBootstrapFuture means embedded metadata is dated in the future.
	ReadinessIssueEmbeddedBootstrapFuture = "embedded_bootstrap_future"
	// ReadinessIssueEmbeddedBootstrapStale means the configured age budget was exceeded.
	ReadinessIssueEmbeddedBootstrapStale = "embedded_bootstrap_stale"
	// ReadinessIssueEmbeddedBootstrapOversize means the configured size budget was exceeded.
	ReadinessIssueEmbeddedBootstrapOversize = "embedded_bootstrap_oversize"
)

Functions

func EmbeddedBuilder

func EmbeddedBuilder() (*catalogs.Builder, error)

EmbeddedBuilder returns a catalog builder loaded from the generation embedded in this module. Consumers use it to construct catalog fixtures without provisioning client storage. Callers that need the verified immutable generation with durable storage should construct a Client.

Types

type Candidate

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

Candidate is a complete immutable catalog prepared off to the side for one atomic publication. Evidence does not alter catalog facts.

func NewCandidate

func NewCandidate(
	catalog *catalogs.Catalog,
	evidence CandidateEvidence,
) (*Candidate, error)

NewCandidate validates and returns a publication candidate. Empty evidence is permitted for custom acquisition. Client.Update records a deterministic custom-update observation in that case.

type CandidateEvidence

type CandidateEvidence struct {
	SourceObservations []catalogs.SourceObservationLink
	ReviewCandidates   []catalogevidence.ReviewCandidate
}

CandidateEvidence binds one publication candidate to its immutable source observations and excluded model review candidates.

type CatalogPublishedEvent

type CatalogPublishedEvent struct {
	GenerationID string
	SyncRunID    string
	Sequence     uint64
	Catalog      *catalogs.Catalog
}

CatalogPublishedEvent identifies one durably committed immutable catalog. Sequence increases with each in-process activation; gaps tell observers that pending callback delivery coalesced to a newer generation. Catalog is safe to retain and share across goroutines.

type CatalogPublishedHook

type CatalogPublishedHook func(CatalogPublishedEvent) error

CatalogPublishedHook is called after a catalog generation is durably committed and atomically published.

type CatalogReadiness

type CatalogReadiness struct {
	Ready    bool                  `json:"ready"`
	Embedded EmbeddedBootstrapInfo `json:"embedded_bootstrap"`
	Issues   []ReadinessIssue      `json:"issues,omitempty"`
}

CatalogReadiness reports whether the current immutable catalog is safe to serve and includes embedded-bootstrap generation evidence.

type CatalogState

type CatalogState struct {
	Catalog         *catalogs.Catalog
	GenerationID    string
	PayloadChecksum string
	GeneratedAt     time.Time
	Sequence        uint64
}

CatalogState holds one atomic snapshot. It pairs the current immutable catalog with its generation identity, checksum, timestamp, and local sequence.

type Client

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

Client manages an immutable canonical catalog, explicit publication, persistence, and event hooks. It owns no provider acquisition, scheduling goroutine, or cadence.

func New

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

New creates a Client using a background context. Call NewContext when construction may perform storage I/O that must be canceled by the caller.

func NewContext

func NewContext(ctx context.Context, opts ...Option) (*Client, error)

NewContext creates a Client with the given options. The caller-owned context bounds durable generation loading and workspace repair and must be non-nil. When a durable generation and a marker-backed unchanged YAML workspace are both configured, construction repairs a stale or interrupted projection by digest. It never overwrites an unrecognized semantic workspace change.

func (*Client) Activate

func (c *Client) Activate(ctx context.Context, generation catalogs.Generation) (Publication, error)

Activate validates, durably commits, and atomically activates an immutable generation obtained by an explicit trusted distribution adapter.

func (*Client) Catalog

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

Catalog returns the current immutable canonical catalog. It returns nil when called on a nil Client. After New or NewContext succeeds, Catalog is non-failing, non-nil, O(1), allocation-free, and safe to retain across goroutines.

func (*Client) CurrentCatalogState

func (c *Client) CurrentCatalogState() CatalogState

CurrentCatalogState returns one atomic catalog/generation pair.

func (*Client) CurrentGeneration

func (c *Client) CurrentGeneration(ctx context.Context) (catalogs.Generation, error)

CurrentGeneration returns the exact immutable generation currently published by this client. The embedded bootstrap is returned before durable mutation.

func (*Client) CurrentGenerationID

func (c *Client) CurrentGenerationID() string

CurrentGenerationID returns the logical identity of the currently published catalog. Before the first durable mutation, this is the embedded bootstrap ID.

func (*Client) Generation

func (c *Client) Generation(ctx context.Context, id string) (catalogs.Generation, error)

Generation returns one retained immutable generation by ID.

func (*Client) HookStats

func (c *Client) HookStats() HookDeliveryStats

HookStats returns a lock-free snapshot of callback delivery health.

func (*Client) OnCatalogPublished

func (c *Client) OnCatalogPublished(fn CatalogPublishedHook)

OnCatalogPublished registers a callback for durable catalog publication. Generations begin callback delivery in sequence order. When callbacks lag, delivery retains the running generation and coalesces pending work to the newest committed generation.

func (*Client) OnModelAdded

func (c *Client) OnModelAdded(fn ModelAddedHook)

OnModelAdded registers a callback for when models are added.

func (*Client) OnModelRemoved

func (c *Client) OnModelRemoved(fn ModelRemovedHook)

OnModelRemoved registers a callback for when models are removed.

func (*Client) OnModelUpdated

func (c *Client) OnModelUpdated(fn ModelUpdatedHook)

OnModelUpdated registers a callback for when models are updated.

func (*Client) Readiness

func (c *Client) Readiness() CatalogReadiness

Readiness evaluates catalog availability and configured embedded-bootstrap age/size budgets without performing I/O.

func (*Client) Rollback

func (c *Client) Rollback(ctx context.Context, generationID string) (*RollbackResult, error)

Rollback atomically makes a retained generation current and projects its exact catalog semantics and provenance into the configured human workspace. Repeating a rollback to the current durable generation is idempotent.

func (*Client) Save

func (c *Client) Save() error

Save atomically materializes the current committed generation into a YAML workspace configured at construction. It never publishes a new generation.

func (*Client) SaveTo

func (c *Client) SaveTo(path string) error

SaveTo atomically materializes the current committed generation into path. It never publishes a new generation.

func (*Client) Update

func (c *Client) Update(ctx context.Context, update UpdateFunc) (Publication, error)

Update serializes candidate construction, generation-store CAS, and atomic in-memory publication. Acquisition and scheduling remain explicit caller composition above Client.

func (*Client) WorkspacePath

func (c *Client) WorkspacePath() string

WorkspacePath returns the configured human-editable YAML workspace. An empty path means this client has no filesystem projection.

type EmbeddedBootstrapInfo

type EmbeddedBootstrapInfo struct {
	Active            bool      `json:"active"`
	ManifestVersion   uint64    `json:"manifest_version"`
	GenerationID      string    `json:"generation_id"`
	GeneratedAt       time.Time `json:"generated_at"`
	AgeSeconds        int64     `json:"age_seconds"`
	SchemaVersion     uint64    `json:"schema_version"`
	PayloadChecksum   string    `json:"payload_checksum"`
	PayloadSizeBytes  int64     `json:"payload_size_bytes"`
	MaximumAgeSeconds int64     `json:"maximum_age_seconds,omitempty"`
	MaximumSizeBytes  int64     `json:"maximum_size_bytes,omitempty"`
}

EmbeddedBootstrapInfo reports the exact offline generation embedded in the binary and the budgets applied while it remains active.

type HookDeliveryStats

type HookDeliveryStats struct {
	// Completed is the number of callback invocations that returned or panicked.
	Completed uint64
	// Failures is the number of callbacks that returned an error or panicked.
	Failures uint64
	// Panics is the number of isolated callback panics.
	Panics uint64
	// Coalesced is the number of pending catalog generations superseded by a
	// newer committed generation before callback delivery began.
	Coalesced uint64
	// LastLatency is the duration of the most recently completed callback.
	LastLatency time.Duration
	// MaxLatency is the longest completed callback duration.
	MaxLatency time.Duration
}

HookDeliveryStats reports isolated callback delivery health.

type ModelAddedHook

type ModelAddedHook func(model catalogs.Model)

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

type ModelRemovedHook

type ModelRemovedHook func(model catalogs.Model)

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

type ModelUpdatedHook

type ModelUpdatedHook func(old, updated catalogs.Model)

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

type Option

type Option func(*options) error

Option is a function that configures a Starmap instance.

func WithCatalogPath

func WithCatalogPath(path string) Option

WithCatalogPath configures the human-editable provider YAML workspace used for both local observation and post-commit materialization. Immutable generation state remains in the separately supplied CatalogStore.

func WithCatalogStore

func WithCatalogStore(store storage.Store) Option

WithCatalogStore configures the writable generation store used by non-dry sync, manual, remote, and scheduled catalog updates. Read-only access and dry runs do not require a store. Starmap provides memory, filesystem, and conditional object-storage implementations; embedding applications own and inject any database-backed implementation.

func WithEmbeddedBootstrapMaxAge

func WithEmbeddedBootstrapMaxAge(maxAge time.Duration) Option

WithEmbeddedBootstrapMaxAge fails readiness while the active catalog is the embedded bootstrap and its generation age exceeds maxAge.

func WithEmbeddedBootstrapMaxSizeBytes

func WithEmbeddedBootstrapMaxSizeBytes(maxSizeBytes int64) Option

WithEmbeddedBootstrapMaxSizeBytes fails readiness while the active embedded bootstrap canonical payload exceeds maxSizeBytes.

type Publication

type Publication struct {
	Published       bool
	GenerationID    string
	PayloadChecksum string
	SyncRunID       string
}

Publication identifies the durable generation produced by a successful update. Published is false when the update function intentionally returns no candidate or an identical retained generation is activated again.

type ReadinessIssue

type ReadinessIssue struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ReadinessIssue is one stable machine-readable reason a client is not ready.

type RollbackResult

type RollbackResult struct {
	// FromGenerationID is the generation active before rollback.
	FromGenerationID string
	// GenerationID is the retained generation selected by rollback.
	GenerationID string
	// PayloadChecksum identifies the exact immutable generation payload.
	PayloadChecksum string
	// Sequence is the in-process publication sequence after rollback.
	Sequence uint64
	// Projection reports exact workspace restoration or pending repair.
	Projection *projection.Result
}

RollbackResult describes activation of a retained immutable generation.

type UpdateFunc

type UpdateFunc func(context.Context, *catalogs.Catalog) (*Candidate, error)

UpdateFunc builds and validates a complete candidate while Client.Update holds the client's mutation transaction. Returning nil performs no publication. The current catalog is immutable and safe to retain.