catalog

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 2, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package catalog owns Starport's immutable view of Starmap facts and the separately versioned runtime availability used to derive routable models.

Index

Constants

View Source
const (
	// DefaultRemoteActivationInterval bounds propagation from Starmap's atomic
	// subscriber state into Starport's runtime transaction. It causes no network
	// request.
	DefaultRemoteActivationInterval = 250 * time.Millisecond
	// DefaultRemoteFetchTimeout bounds manifest and payload requests. The SSE
	// stream uses Starmap's heartbeat and liveness contract instead.
	DefaultRemoteFetchTimeout = 2 * time.Minute
)
View Source
const DefaultRefreshTimeout = 2 * time.Minute

DefaultRefreshTimeout bounds local catalog acquisition when the application does not configure a positive timeout.

Variables

View Source
var (
	// ErrCatalogSourceRequired reports a missing Starmap catalog source.
	ErrCatalogSourceRequired = errors.New("catalog source is required")
	// ErrCatalogRequired means that a Starmap state has no immutable catalog.
	ErrCatalogRequired = errors.New("catalog state must contain a catalog")
	// ErrModelNotCatalogued reports a model name the retained generation does
	// not hold. It is separate from an unreachable model because the two have
	// different answers: a name the catalog never held is the caller's to
	// correct, and a catalogued model with no reachable provider is the
	// gateway's to report.
	ErrModelNotCatalogued = errors.New("model is not in the catalog")
	// ErrCatalogGenerationRequired means that a Starmap state has no generation identity.
	ErrCatalogGenerationRequired = errors.New("catalog state must contain a generation ID")
	// ErrMissingPagePrice reports an offering that serves document recognition
	// and states no price per page.
	//
	// Recognition is the one operation whose unit is neither a token nor a
	// request, so a token price says nothing about what a page costs. An
	// offering the gateway cannot price is one it would serve for free against
	// real provider time, and a spend limit set on that account would never
	// fire. Planning drops the operation instead of guessing a price.
	ErrMissingPagePrice = errors.New("offering serves document recognition with no page price")
	// ErrRerankUnpriced reports an offering that serves reranking and states
	// no price in the unit it bills.
	//
	// Providers disagree on that unit. Cohere bills a search unit, which is one
	// query against a bounded document count, and Voyage bills the tokens it
	// reads. The offering names its own basis, so an offering that names one
	// and publishes no price for it is a catalog defect rather than a known
	// gap. Planning drops the operation, which keeps a silent zero out of the
	// account's spend total.
	ErrRerankUnpriced = errors.New("offering serves reranking with no price in the unit it bills")
)

Functions

func ProviderFromModelID

func ProviderFromModelID(modelID string) string

ProviderFromModelID returns the adapter ID named by a provider-scoped model ID.

func SplitModelID

func SplitModelID(modelID string) (provider, model string, ok bool)

SplitModelID splits one provider-scoped model ID.

Types

type AdapterAvailability

type AdapterAvailability struct {
	ProviderID    catalogs.ProviderID
	Registered    bool
	Operations    []catalogs.ProviderOperation
	EndpointTypes []catalogs.EndpointType
}

AdapterAvailability is runtime state for one compiled provider adapter. It is not a catalog fact and does not contain operator credential state.

type ControlPlane

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

ControlPlane atomically publishes one routable view derived from an immutable Starmap generation and separately versioned runtime availability.

func Open

func Open(source Source) (*ControlPlane, error)

Open creates the catalog control plane from the source's current atomic state.

func (*ControlPlane) Activate

func (p *ControlPlane) Activate(state starmap.CatalogState) error

Activate validates and atomically publishes one complete catalog generation. Retained older snapshots remain valid and do not observe the new generation.

func (*ControlPlane) Current

func (p *ControlPlane) Current() *RoutableSnapshot

Current returns the current immutable routable snapshot in O(1).

func (*ControlPlane) PublishAvailability

func (p *ControlPlane) PublishAvailability(snapshot availability.Snapshot) error

PublishAvailability applies one availability-owner generation to the derived routable projection. It does not own availability state transitions.

func (*ControlPlane) Refresh

func (p *ControlPlane) Refresh() error

Refresh atomically activates the source's current catalog generation.

func (*ControlPlane) RemoveAdapter

func (p *ControlPlane) RemoveAdapter(providerID catalogs.ProviderID) error

RemoveAdapter removes one runtime adapter and atomically republishes the view.

func (*ControlPlane) ReplaceAdapters

func (p *ControlPlane) ReplaceAdapters(adapters []AdapterAvailability) error

ReplaceAdapters replaces the complete runtime adapter set in one publication.

func (*ControlPlane) ReplaceRuntime added in v1.0.2

func (p *ControlPlane) ReplaceRuntime(
	state starmap.CatalogState,
	adapters []AdapterAvailability,
) (*RoutableSnapshot, error)

ReplaceRuntime atomically publishes one catalog state and complete adapter set. Retained snapshots remain immutable.

func (*ControlPlane) SetAdapter

func (p *ControlPlane) SetAdapter(adapter AdapterAvailability) error

SetAdapter updates one runtime adapter and atomically republishes the derived view.

func (*ControlPlane) ValidateRuntime added in v1.0.2

func (p *ControlPlane) ValidateRuntime(
	state starmap.CatalogState,
	adapters []AdapterAvailability,
) error

ValidateRuntime proves that one catalog state and complete adapter set can produce a routable snapshot without changing published state.

type Diff added in v1.1.0

type Diff struct {
	Available         bool      `json:"available"`
	Reason            string    `json:"reason,omitempty"`
	FromGenerationID  string    `json:"from_generation_id,omitempty"`
	ToGenerationID    string    `json:"to_generation_id,omitempty"`
	FromGeneratedAt   time.Time `json:"from_generated_at,omitzero"`
	ToGeneratedAt     time.Time `json:"to_generated_at,omitzero"`
	SemanticallyEqual bool      `json:"semantically_equal"`

	ModelsAdded      []string         `json:"models_added,omitempty"`
	ModelsRemoved    []string         `json:"models_removed,omitempty"`
	OfferingsAdded   []OfferingChange `json:"offerings_added,omitempty"`
	OfferingsRemoved []OfferingChange `json:"offerings_removed,omitempty"`
	PriceChanges     []PriceChange    `json:"price_changes,omitempty"`
}

Diff compares the previous accepted generation against the current one. When only one generation is recorded, Available is false and Reason says why — that is a normal state, not an error.

type FreshnessService added in v1.1.0

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

FreshnessService reads catalog freshness from the active snapshot and the durable generation store. It never mutates either.

func NewFreshnessService added in v1.1.0

func NewFreshnessService(snapshots SnapshotSource, generations *GenerationStore) *FreshnessService

NewFreshnessService creates the freshness read service.

func (*FreshnessService) Changes added in v1.1.0

func (s *FreshnessService) Changes(ctx context.Context) (Diff, error)

Changes diffs the previous accepted generation against the current one.

func (*FreshnessService) Metadata added in v1.1.0

Metadata reports the active snapshot's identity, age, and manifest facts.

type GenerationIndexEntry added in v1.1.0

type GenerationIndexEntry struct {
	GenerationID     string    `json:"generation_id"`
	GeneratedAt      time.Time `json:"generated_at"`
	PayloadChecksum  string    `json:"payload_checksum"`
	SemanticChecksum string    `json:"semantic_checksum,omitempty"`
}

GenerationIndexEntry records one accepted generation in acceptance order. The semantic checksum excludes provenance, so the diff service can skip provenance-only churn without decoding payloads.

type GenerationStore

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

GenerationStore adapts Starport's configured KV store to Starmap's durable immutable-generation contract.

func NewGenerationStore

func NewGenerationStore(store storage.KVStore) (*GenerationStore, error)

NewGenerationStore creates a durable Starmap generation store.

func (*GenerationStore) Commit

func (s *GenerationStore) Commit(
	ctx context.Context,
	generation catalogs.Generation,
	expectedGenerationID string,
) error

Commit stores one immutable generation, then selects it with compare-and-swap.

func (*GenerationStore) Current

Current returns the atomically selected generation.

func (*GenerationStore) Get

func (s *GenerationStore) Get(ctx context.Context, generationID string) (catalogs.Generation, error)

Get returns one immutable generation by ID.

func (*GenerationStore) History added in v1.1.0

History returns accepted generations in acceptance order, oldest first. A store without an index (the remote head store) reports no history.

type OfferingChange added in v1.1.0

type OfferingChange struct {
	Provider        string `json:"provider"`
	ProviderModelID string `json:"provider_model_id"`
	DefinitionID    string `json:"definition_id"`
}

OfferingChange identifies one provider offering added or removed between two accepted generations.

type OfferingRoutability added in v1.1.0

type OfferingRoutability struct {
	ProviderID      catalogs.ProviderID
	ProviderModelID catalogs.ProviderModelID
	Routable        bool
	Exclusion       RouteExclusion
}

OfferingRoutability is the planning verdict for one exact catalog offering. The verdict set is total: every offering in the generation carries one, so a caller can tell an advertised offering apart from a reachable one.

type PriceChange added in v1.1.0

type PriceChange struct {
	Provider        string  `json:"provider"`
	ProviderModelID string  `json:"provider_model_id"`
	DefinitionID    string  `json:"definition_id"`
	Field           string  `json:"field"`
	PreviousPer1M   float64 `json:"previous_per_1m"`
	CurrentPer1M    float64 `json:"current_per_1m"`
}

PriceChange reports one token-price movement on an offering present in both generations. Values are USD per one million tokens.

type RefreshReport added in v1.1.0

type RefreshReport struct {
	PreviousGenerationID string    `json:"previous_generation_id"`
	GenerationID         string    `json:"generation_id"`
	GeneratedAt          time.Time `json:"generated_at"`
	Changed              bool      `json:"changed"`
}

RefreshReport summarizes one forced catalog acquisition.

type RemoteConfig added in v1.0.2

type RemoteConfig struct {
	BaseURL            string
	APIKey             string
	ActivationInterval time.Duration
	FetchTimeout       time.Duration
	HTTPClient         *http.Client
}

RemoteConfig defines one verified Starmap publication source.

type RemoteRuntime added in v1.0.2

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

RemoteRuntime owns the verified Starmap subscriber, its durable remote head, and Starport's separate accepted runtime generation.

func OpenRemoteRuntime added in v1.0.2

func OpenRemoteRuntime(
	ctx context.Context,
	store storage.KVStore,
	config RemoteConfig,
) (*RemoteRuntime, error)

OpenRemoteRuntime creates an idle remote runtime without starting network or background work.

func (*RemoteRuntime) Accept added in v1.0.2

func (r *RemoteRuntime) Accept(ctx context.Context, state starmap.CatalogState) error

Accept records a generation after Starport builds and validates the complete runtime candidate. The remote and accepted current pointers remain independent.

func (*RemoteRuntime) Close added in v1.0.2

func (r *RemoteRuntime) Close(ctx context.Context) error

Close stops and joins all remote runtime work.

func (*RemoteRuntime) ControlPlane added in v1.0.2

func (r *RemoteRuntime) ControlPlane() *ControlPlane

ControlPlane returns the last accepted Starport runtime catalog.

func (*RemoteRuntime) CurrentCandidate added in v1.0.2

func (r *RemoteRuntime) CurrentCandidate() starmap.CatalogState

CurrentCandidate returns the subscriber's current atomic state without I/O.

func (*RemoteRuntime) RefreshCandidate added in v1.1.0

func (r *RemoteRuntime) RefreshCandidate(
	ctx context.Context,
	timeout time.Duration,
) (starmap.CatalogState, error)

RefreshCandidate returns the verified subscriber state without network I/O. Remote publication and retry work belongs to Start.

func (*RemoteRuntime) Start added in v1.0.2

func (r *RemoteRuntime) Start(ctx context.Context) error

Start starts the Starmap remote lifecycle and the local atomic-state sampler.

func (*RemoteRuntime) Sync added in v1.0.2

Sync returns the current verified subscriber state without network I/O. Remote publication and retry work belongs to Start.

func (*RemoteRuntime) Updates added in v1.0.2

func (r *RemoteRuntime) Updates() <-chan starmap.CatalogState

Updates returns verified atomic states after the initial candidate.

type RoutableSnapshot

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

RoutableSnapshot projects one Starmap generation and one runtime availability revision into an immutable route set.

func (*RoutableSnapshot) AvailabilityRevision

func (s *RoutableSnapshot) AvailabilityRevision() uint64

AvailabilityRevision returns the runtime availability revision.

func (*RoutableSnapshot) Catalog

func (s *RoutableSnapshot) Catalog() *catalogs.Catalog

Catalog returns the retained immutable Starmap catalog. Starmap guarantees that published catalogs are safe to share and retain across goroutines.

func (*RoutableSnapshot) CatalogSequence

func (s *RoutableSnapshot) CatalogSequence() uint64

CatalogSequence returns the source's monotonic generation sequence.

func (*RoutableSnapshot) Definition

Definition returns one caller-owned definition from this exact generation.

func (*RoutableSnapshot) Definitions

func (s *RoutableSnapshot) Definitions() []catalogs.ModelDefinition

Definitions returns caller-owned Starmap definitions that have a routable offering.

func (*RoutableSnapshot) GeneratedAt

func (s *RoutableSnapshot) GeneratedAt() time.Time

GeneratedAt returns the Starmap generation timestamp.

func (*RoutableSnapshot) GenerationID

func (s *RoutableSnapshot) GenerationID() string

GenerationID returns the Starmap generation used to derive this snapshot.

func (*RoutableSnapshot) LowestPagePrice added in v1.1.0

func (s *RoutableSnapshot) LowestPagePrice(operation catalogs.ProviderOperation) (float64, bool)

LowestPagePrice returns the cheapest page price this generation publishes for one operation.

It answers the question a caller has before a route exists: what is the least this document can cost to read? The planner picks the offering afterwards, so no exact price is knowable yet, and the cheapest one is the only bound that refuses no work the account could have paid for.

func (*RoutableSnapshot) LowestSearchUnitPrice added in v1.1.0

func (s *RoutableSnapshot) LowestSearchUnitPrice(modelID string) (float64, bool)

LowestSearchUnitPrice returns the cheapest search unit price this generation publishes for one model's rerank offerings.

It answers the question a spend budget has before a route exists: what is the least this rerank call can cost? The planner picks the offering afterwards, so no exact price is knowable yet, and the cheapest one is the only bound that refuses no work the account could have paid for. An offering that bills tokens rather than search units states no floor at all before the provider has read the documents, so it answers nothing and the budget refuses nothing.

func (*RoutableSnapshot) Names added in v1.1.0

func (s *RoutableSnapshot) Names(modelID string) bool

Names reports whether this generation holds one model name at all. It reads every offering the generation carries and not the routable subset, because a name whose provider has no credential today is still a name the catalog holds. A caller that used the routable set here would answer a configuration gap with "no such model" and send an operator looking for a typo.

It accepts the same two spellings ResolveRoute accepts: a provider-scoped route ID and a canonical definition ID.

func (*RoutableSnapshot) Offering

func (s *RoutableSnapshot) Offering(route Route) (catalogs.ProviderOffering, error)

Offering returns one caller-owned offering from this exact generation.

func (*RoutableSnapshot) OfferingRoutability added in v1.1.0

func (s *RoutableSnapshot) OfferingRoutability() []OfferingRoutability

OfferingRoutability returns the planning verdict for every offering in the generation, routable or not, sorted by provider and provider model ID.

func (*RoutableSnapshot) PagePriceFor added in v1.1.0

func (s *RoutableSnapshot) PagePriceFor(
	modelID string,
	operation catalogs.ProviderOperation,
) (float64, bool)

PagePriceFor returns what one model charges to read one page of a document, in USD. A page is the unit recognition is billed in, and no token price converts into it.

func (*RoutableSnapshot) PayloadChecksum added in v1.0.2

func (s *RoutableSnapshot) PayloadChecksum() string

PayloadChecksum returns the checksum bound to the Starmap generation.

func (*RoutableSnapshot) ResolveOperation

func (s *RoutableSnapshot) ResolveOperation(
	modelID string,
	operation catalogs.ProviderOperation,
) (Route, bool)

ResolveOperation resolves only routes that support one exact operation.

func (*RoutableSnapshot) ResolveRoute

func (s *RoutableSnapshot) ResolveRoute(modelID string) (Route, bool)

ResolveRoute resolves a provider-scoped route ID or a canonical definition ID to the first stable routable offering.

func (*RoutableSnapshot) Routes

func (s *RoutableSnapshot) Routes() []Route

Routes returns a caller-owned copy of the routable offering identities.

func (*RoutableSnapshot) RoutesForDefinition

func (s *RoutableSnapshot) RoutesForDefinition(definitionID catalogs.ModelDefinitionID) []Route

RoutesForDefinition returns routable offerings for one canonical model.

func (*RoutableSnapshot) RoutesForProvider

func (s *RoutableSnapshot) RoutesForProvider(providerID catalogs.ProviderID) []Route

RoutesForProvider returns routable offerings for one provider in stable order.

type Route

type Route struct {
	CatalogGenerationID string
	DefinitionID        catalogs.ModelDefinitionID
	ProviderID          catalogs.ProviderID
	ProviderModelID     catalogs.ProviderModelID
	Operations          []catalogs.ProviderOperation
	Endpoints           []catalogs.ProviderOfferingEndpoint
	PromptCache         *bool
}

Route is one immutable, generation-bound provider offering identity.

func (Route) Endpoint

Endpoint returns the exact Starmap endpoint for a supported operation.

func (Route) ID

func (r Route) ID() string

ID returns Starport's provider-scoped route ID.

func (Route) Key

func (r Route) Key() catalogs.OfferingKey

Key returns the exact Starmap provider offering identity.

func (Route) Supports

func (r Route) Supports(operation catalogs.ProviderOperation) bool

Supports reports whether the catalog offering and compiled adapter both support the operation.

func (Route) SupportsPromptCache

func (r Route) SupportsPromptCache() bool

SupportsPromptCache reports exact offering support. Unknown is not support.

type RouteExclusion added in v1.1.0

type RouteExclusion string

RouteExclusion names the derivation filter that kept one catalog offering out of the routable set. It is the route planner's own vocabulary. A caller that reports operator state maps it into its own reason words.

const (
	// RouteExclusionNone marks an offering that planning kept.
	RouteExclusionNone RouteExclusion = ""
	// RouteExclusionAdapterNotReady reports that the provider has no adapter
	// able to carry a request, so none of its offerings can be reached.
	RouteExclusionAdapterNotReady RouteExclusion = "adapter_not_ready"
	// RouteExclusionCatalogRetired reports a retired offering lifecycle.
	RouteExclusionCatalogRetired RouteExclusion = "catalog_retired"
	// RouteExclusionCatalogUnavailable reports catalog-declared unavailability.
	RouteExclusionCatalogUnavailable RouteExclusion = "catalog_unavailable"
	// RouteExclusionOfferingUnavailable reports that the availability owner
	// currently withholds this offering.
	RouteExclusionOfferingUnavailable RouteExclusion = "offering_unavailable"
	// RouteExclusionOperationUnsupported reports that the offering and the
	// adapter share no operation with a usable endpoint. The offering exists in
	// the catalog and is healthy, and no request can reach it.
	RouteExclusionOperationUnsupported RouteExclusion = "operation_unsupported"
	// RouteExclusionOperationUnpriced reports that every operation the offering
	// and the adapter share is one the gateway cannot bill. It is a separate
	// verdict from operation_unsupported because the fix is a catalog price,
	// not a compiled adapter.
	RouteExclusionOperationUnpriced RouteExclusion = "operation_unpriced"
)

Route exclusions are a closed set, ordered the way the derivation applies them. An offering carries the first exclusion that rejected it.

type Runtime

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

Runtime owns one Starmap client, its acquisition path, and Starport's derived immutable routable control plane.

func OpenRuntime

func OpenRuntime(
	ctx context.Context,
	store storage.KVStore,
	workspacePath string,
	options ...acquisition.Option,
) (*Runtime, error)

OpenRuntime constructs the catalog runtime over Starport's durable storage. Starmap alone resolves catalog-acquisition credentials.

func (*Runtime) ControlPlane

func (r *Runtime) ControlPlane() *ControlPlane

ControlPlane returns Starport's generation-consistent catalog projection.

func (*Runtime) PublishObservations

func (r *Runtime) PublishObservations(
	ctx context.Context,
	observations ...sources.Observation,
) (starmap.Publication, error)

PublishObservations reconciles account or operator observations through Starmap, then activates the resulting immutable generation.

func (*Runtime) Refresh

func (r *Runtime) Refresh(ctx context.Context, options ...pkgsync.Option) (*pkgsync.Result, error)

Refresh runs Starmap acquisition and publishes any new generation into the Starport routable view.

func (*Runtime) RefreshCandidate added in v1.1.0

func (r *Runtime) RefreshCandidate(
	ctx context.Context,
	timeout time.Duration,
) (starmap.CatalogState, error)

RefreshCandidate acquires the standard provider and local catalog sources. It returns the complete unpublished state for runtime-candidate construction.

func (*Runtime) Sync added in v1.0.2

func (r *Runtime) Sync(
	ctx context.Context,
	options ...pkgsync.Option,
) (*pkgsync.Result, starmap.CatalogState, error)

Sync runs Starmap acquisition and returns the complete unpublished catalog state for runtime-candidate construction.

type SnapshotMetadata added in v1.1.0

type SnapshotMetadata struct {
	GenerationID         string    `json:"generation_id"`
	GeneratedAt          time.Time `json:"generated_at"`
	AgeSeconds           int64     `json:"age_seconds"`
	CatalogSequence      uint64    `json:"catalog_sequence"`
	AvailabilityRevision uint64    `json:"availability_revision"`
	PayloadChecksum      string    `json:"payload_checksum"`

	ManifestAvailable         bool   `json:"manifest_available"`
	ManifestUnavailableReason string `json:"manifest_unavailable_reason,omitempty"`

	SchemaVersion      uint64              `json:"schema_version,omitempty"`
	PayloadSizeBytes   int64               `json:"payload_size_bytes,omitempty"`
	Completeness       string              `json:"completeness,omitempty"`
	Degraded           bool                `json:"degraded"`
	DegradationReasons []string            `json:"degradation_reasons,omitempty"`
	Validation         ValidationSummary   `json:"validation,omitzero"`
	SourceObservations []SourceObservation `json:"source_observations,omitempty"`
	SyncRunID          string              `json:"sync_run_id,omitempty"`
}

SnapshotMetadata is the freshness surface of the active catalog snapshot. The scalar identity always comes from the snapshot itself. Manifest detail comes from the stored generation record; when that record is missing the metadata says so instead of silently omitting fields.

type SnapshotSource added in v1.1.0

type SnapshotSource interface {
	Current() *RoutableSnapshot
}

SnapshotSource supplies the active routable snapshot.

type Source

type Source interface {
	CurrentCatalogState() starmap.CatalogState
}

Source supplies one atomic Starmap catalog and generation pair.

type SourceObservation added in v1.1.0

type SourceObservation struct {
	Source       string    `json:"source"`
	ObservedAt   time.Time `json:"observed_at"`
	Completeness string    `json:"completeness"`
	Status       string    `json:"status"`
}

SourceObservation reports one acquisition source that fed the generation.

type ValidationSummary added in v1.1.0

type ValidationSummary struct {
	Status       string    `json:"status"`
	ErrorCount   int       `json:"error_count"`
	WarningCount int       `json:"warning_count"`
	ValidatedAt  time.Time `json:"validated_at"`
}

ValidationSummary condenses the generation validation report for operators.

Directories

Path Synopsis
Package logos serves the bundled catalog identity marks.
Package logos serves the bundled catalog identity marks.
Package view owns the console- and API-facing projections of one routable catalog snapshot.
Package view owns the console- and API-facing projections of one routable catalog snapshot.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL