material

Documentation

Overview

Package search provides a unified interface for material/asset search across multiple backends (stock platforms, OSS, local vector stores).

Index

• Constants
• func EncodePagination(state PaginationState) string
• func Register(scheme string, ctor Constructor)
• func Retry(fn func() error, maxAttempts int, baseDelay time.Duration) error
• func RetryWithContext(ctx context.Context, fn func() error, maxAttempts int, baseDelay time.Duration) error
• type BackendError
  • func (e BackendError) Error() string
• type Constructor
• type Describer
• type Item
• type MultiOption
  • func WithTimeout(d time.Duration) MultiOption
• type MultiResult
• type MultiSearcher
  • func NewFromEnv() (*MultiSearcher, error)
  • func NewFromURIs(uris string) (*MultiSearcher, error)
  • func NewMultiSearcher(backends ...Searcher) *MultiSearcher
  • func NewMultiSearcherWithOptions(backends []Searcher, opts ...MultiOption) *MultiSearcher
  • func (m *MultiSearcher) Search(ctx context.Context, req Request) (Result, error)
  • func (m *MultiSearcher) SearchMulti(ctx context.Context, req Request) MultiResult
• type PaginationState
  • func DecodePagination(token string) PaginationState
• type ParsedURI
  • func ParseURI(raw string) (ParsedURI, error)
  • func ParseURIs(raw string) ([]ParsedURI, error)
• type RateLimiter
  • func NewRateLimiter(rpm int) *RateLimiter
  • func (rl *RateLimiter) Stop()
  • func (rl *RateLimiter) Wait(ctx context.Context) error
• type Request
• type Result
• type Searcher
  • func NewSearcher(uri string) (Searcher, error)

Constants

const (
	// EnvMaterialURIs is the combined URI list env var.
	// Format: comma-separated URIs, e.g. "pexels://KEY,unsplash://KEY,oss://AK:SK@bucket.region"
	EnvMaterialURIs = "MATERIAL_URIS"

	// Per-backend URI env vars.
	EnvPexelsURI   = "PEXELS_URI"
	EnvUnsplashURI = "UNSPLASH_URI"
	EnvPixabayURI  = "PIXABAY_URI"
	EnvOSSURI      = "OSS_META_URI"
	EnvLocalURI    = "LOCAL_MATERIAL_URI"
)

Environment variable names for URI-based configuration.

Functions

func EncodePagination

func EncodePagination(state PaginationState) string

EncodePagination serializes pagination state into a single opaque token.

func Register

func Register(scheme string, ctor Constructor)

Register adds a backend constructor for the given scheme.

func Retry

func Retry(fn func() error, maxAttempts int, baseDelay time.Duration) error

Retry executes fn with exponential backoff and jitter. Retries up to maxAttempts times on error. Returns the last error if all attempts fail.

func RetryWithContext

func RetryWithContext(ctx context.Context, fn func() error, maxAttempts int, baseDelay time.Duration) error

RetryWithContext executes fn with exponential backoff, respecting context cancellation.

Types

type BackendError

type BackendError struct {
	Source string
	Err    error
}

BackendError records a single backend failure during multi-search.

func (BackendError) Error

func (e BackendError) Error() string

type Constructor

type Constructor func(parsed ParsedURI) (Searcher, error)

Constructor builds a Searcher from a parsed URI.

type Describer

type Describer interface {
	// Source returns the backend identifier (e.g. "pexels", "unsplash", "oss").
	Source() string
	// SupportedMediaTypes returns the media types this searcher can find.
	SupportedMediaTypes() []string
}

Describer is an optional interface for searchers to advertise capabilities.

type Item

type Item struct {
	ID          string            `json:"id"`
	URI         string            `json:"uri"`
	Filename    string            `json:"filename,omitempty"`
	PreviewURL  string            `json:"preview_url,omitempty"`
	DownloadURL string            `json:"download_url,omitempty"`
	Size        int64             `json:"size,omitempty"`
	MediaType   string            `json:"media_type"`
	ContentType string            `json:"content_type,omitempty"`
	Width       int               `json:"width,omitempty"`
	Height      int               `json:"height,omitempty"`
	Duration    float64           `json:"duration,omitempty"`
	Source      string            `json:"source"`
	Author      string            `json:"author,omitempty"`
	License     string            `json:"license,omitempty"`
	Tags        []string          `json:"tags,omitempty"`
	Score       float64           `json:"score,omitempty"`
	Caption     string            `json:"caption,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

Item represents a single search result.

type MultiOption

type MultiOption func(*MultiSearcher)

MultiOption configures MultiSearcher behavior.

func WithTimeout

func WithTimeout(d time.Duration) MultiOption

WithTimeout sets a per-backend timeout. If a backend doesn't respond within this duration, its results are skipped. Default: 15s.

type MultiResult

type MultiResult struct {
	Result
	Errors []BackendError
}

MultiResult extends Result with partial failure information.

type MultiSearcher

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

MultiSearcher aggregates multiple Searcher backends and merges results.

func NewFromEnv

func NewFromEnv() (*MultiSearcher, error)

NewFromEnv creates a MultiSearcher from environment variables.

Resolution order:

1. MATERIAL_URIS — if set, parsed as comma-separated URI list (takes precedence)
2. Per-backend env vars: PEXELS_URI, UNSPLASH_URI, PIXABAY_URI, OSS_META_URI, LOCAL_MATERIAL_URI

Returns nil if no env vars are configured.

func NewFromURIs

func NewFromURIs(uris string) (*MultiSearcher, error)

NewFromURIs creates a MultiSearcher from a comma-separated URI list. Each URI configures one backend; all backends are aggregated into a single searcher.

Example:

searcher, err := search.NewFromURIs("pexels://KEY1,unsplash://KEY2,oss://AK:SK@bucket.cn-hangzhou")

func NewMultiSearcher

func NewMultiSearcher(backends ...Searcher) *MultiSearcher

NewMultiSearcher creates a searcher that queries multiple backends concurrently.

func NewMultiSearcherWithOptions

func NewMultiSearcherWithOptions(backends []Searcher, opts ...MultiOption) *MultiSearcher

NewMultiSearcherWithOptions creates a MultiSearcher with custom options.

func (*MultiSearcher) Search

func (m *MultiSearcher) Search(ctx context.Context, req Request) (Result, error)

Search queries all backends concurrently and merges results. Partial failures are tolerated — failed backends are recorded in MultiResult.Errors.

func (*MultiSearcher) SearchMulti

func (m *MultiSearcher) SearchMulti(ctx context.Context, req Request) MultiResult

SearchMulti is like Search but returns MultiResult with error details and a composite NextToken for pagination across backends.

type PaginationState

type PaginationState map[string]string // source → next_token or page

PaginationState encodes per-backend pagination cursors for MultiSearcher. Serialized as base64 JSON in NextToken to allow transparent continuation.

func DecodePagination

func DecodePagination(token string) PaginationState

DecodePagination deserializes an opaque token back into pagination state. Returns empty state (not an error) if the token is empty or invalid.

type ParsedURI

type ParsedURI struct {
	Scheme string // "pexels", "unsplash", "pixabay", "oss", "local"

	// Common auth
	APIKey string // primary key (api_key, access_key)
	Secret string // secondary secret (oss access_key_secret)

	// OSS specific
	Bucket        string
	Region        string
	Mode          string // "basic" or "semantic"
	SecurityToken string

	// Local specific
	IndexPath    string
	EmbedBackend string // "dashscope", "jina", "openai", "voyage", "gemini"
	EmbedKey     string // API key for embedding engine
	EmbedModel   string // optional model override

	// Generic
	Params url.Values // all query parameters
}

ParsedURI holds the parsed components of a search backend URI.

func ParseURI

func ParseURI(raw string) (ParsedURI, error)

ParseURI parses a single search backend URI into its components.

func ParseURIs

func ParseURIs(raw string) ([]ParsedURI, error)

ParseURIs parses a comma-separated list of search backend URIs.

type RateLimiter

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

RateLimiter provides simple token-bucket rate limiting for search backends.

func NewRateLimiter

func NewRateLimiter(rpm int) *RateLimiter

NewRateLimiter creates a rate limiter that allows rpm requests per minute.

func (*RateLimiter) Stop

func (rl *RateLimiter) Stop()

Stop releases the rate limiter resources.

func (*RateLimiter) Wait

func (rl *RateLimiter) Wait(ctx context.Context) error

Wait blocks until a token is available or context is cancelled.

type Request

type Request struct {
	Query      string   // keyword or natural language description
	MediaTypes []string // filter: "image", "video", "audio", "document"
	Tags       []string // tag filters
	MaxResults int      // max items to return (1-100)
	Page       int      // pagination page number (1-based)
	Sort       string   // "relevance", "newest", "popular"
	Order      string   // "asc", "desc"
	NextToken  string   // cursor for continuation
	Locale     string   // "zh", "en", etc.

	// OSS MetaQuery basic mode fields
	FieldQuery  string // structured JSON query for scalar search
	SimpleQuery string // additional filter for semantic mode
}

Request describes what to search for.

type Result

type Result struct {
	Items     []Item `json:"items"`
	Total     int    `json:"total"`
	NextToken string `json:"next_token,omitempty"`
	Source    string `json:"source"`
}

Result is the outcome of a search operation.

type Searcher

type Searcher interface {
	Search(ctx context.Context, req Request) (Result, error)
}

Searcher searches for materials/assets from a specific backend.

func NewSearcher

func NewSearcher(uri string) (Searcher, error)

NewSearcher creates a single Searcher from a URI string.