vega

Documentation

Overview

Package vega harvests peer libraries' subject cataloging from III Vega Discover catalogs (NYPL and other Innovative sites) through the anonymous JSON API at <region>.iiivega.com. Unlike BiblioCommons' reverse RSS inference, Vega states its vocabulary outright: a concept record carries source="homoit", so a match is a peer's explicit Homosaurus assertion.

The chain per driver term: suggestions?phrase=<label> yields concept candidates; the concept endpoint gates source=="homoit" and an exact label match; the resources endpoint pages the FormatGroups cataloged under the concept, each carrying typed identifiers (ISBN on ~89% of records). Matching back to our works is by ISBN; the driver term is the suggestion.

Concept UUIDs are shared REGION-wide (every tenant in na returns the same UUID for one label), so label->concept resolution runs once per region and every tenant there reuses it. All of a region's traffic hits one API host, so politeness is per REGION: requests within a region serialize with the delay, distinct regions run concurrently.

Index

• Constants
• type Doer
• type Enricher
  • func New(tenants []Tenant, terms []Term, opts ...Option) *Enricher
  • func (e *Enricher) Describe() string
  • func (e *Enricher) Enrich(ctx context.Context, works []ingest.WorkSummary) ([]ingest.Enrichment, error)
  • func (e *Enricher) Name() string
  • func (e *Enricher) RunStats() ingest.EnrichStats
• type Option
  • func WithCacheTTL(d time.Duration) Option
  • func WithClient(d Doer) Option
  • func WithDelay(d time.Duration) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithMaxPages(n int) Option
• type Tenant
  • func ParseTenants(spec string) ([]Tenant, error)
  • func (t Tenant) Key() string
• type Term

Constants

const Name = "vega"

Name is the enrichment source name; suggestions carry PIPELINE provenance.

Types

type Doer

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

Doer is the HTTP seam, injectable for tests.

type Enricher

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

Enricher harvests one or more Vega tenants.

func New

func New(tenants []Tenant, terms []Term, opts ...Option) *Enricher

New returns the harvester for the given tenants and driver term list.

func (*Enricher) Describe

func (e *Enricher) Describe() string

Describe names the peer catalogs this enricher pulls from.

func (*Enricher) Enrich

func (e *Enricher) Enrich(ctx context.Context, works []ingest.WorkSummary) ([]ingest.Enrichment, error)

Enrich implements ingest.Enricher: per region, resolve each driver term to its shared concept once; per tenant, page the concept's FormatGroups (memoized within the TTL); match ISBNs back to the scoped works; emit one suggestion per (work, term) endorsed by every corroborating tenant.

func (*Enricher) Name

func (e *Enricher) Name() string

Name implements ingest.Enricher.

func (*Enricher) RunStats

func (e *Enricher) RunStats() ingest.EnrichStats

RunStats implements ingest.StatsReporter: Total is tenants x driver terms, Batches the (tenant, term) harvests completed (cache-warm counted instantly), SkippedBatches the per-tenant terms abandoned on an error, Candidates the live matches so far. Safe mid-run.

type Option

type Option func(*Enricher)

Option configures the enricher.

func WithCacheTTL

func WithCacheTTL(d time.Duration) Option

WithCacheTTL overrides how long resolutions and harvests are reused.

func WithClient

func WithClient(d Doer) Option

WithClient injects the HTTP client (tests).

func WithDelay

func WithDelay(d time.Duration) Option

WithDelay overrides the politeness pause.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger wires progress logging.

func WithMaxPages

func WithMaxPages(n int) Option

WithMaxPages caps resources pages fetched per (tenant, concept).

type Tenant

type Tenant struct {
	SiteCode string
	Region   string // "na", "na2", ...
}

Tenant is one Vega library: the catalog subdomain and its region. The catalog lives at https://<SiteCode>.<Region>.iiivega.com/ (some sites front it with a custom domain, but the Vega-domain form answers for all).

func ParseTenants

func ParseTenants(spec string) ([]Tenant, error)

ParseTenants reads the config form: comma-separated <siteCode>.<region> entries ("nypl.na2,mdpls.na"). The siteCode must be the library's real catalog subdomain -- DNS is wildcard, so nothing validates a guess until the API answers 403 "Customer with siteCode not found".

func (Tenant) Key

func (t Tenant) Key() string

Key is the tenant's display / attribution identity ("nypl.na2").

type Term

type Term struct {
	URI    string
	Labels map[string]string
	// Query is the resolution label (the English prefLabel).
	Query string
}

Term is one driver term: the vocabulary URI the suggestion will carry and the label to resolve against the peer's concepts.