voyage

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package voyage provides bounded, stateless multimodal embedding of images and video through the Voyage AI API.

Uploads fail closed unless an operator has run the authenticated capability probe and supplied its validated manifest. Each media format, animated image support, video, and query mode is authorized separately by recorded probe evidence rather than by assumption.

The package detects and bounds media through go.kenn.io/docbank/document/media and never persists media bytes, vectors, or provider responses. Consent, spending limits, orchestration, vector storage, and search remain the importing application's responsibility.

Index

Constants

View Source 
const (
	CapabilityImageJPEG        = "image_jpeg"
	CapabilityImagePNG         = "image_png"
	CapabilityImageWebP        = "image_webp"
	CapabilityImageGIFStill    = "image_gif_still"
	CapabilityImageGIFAnimated = "image_gif_animated"
	CapabilityVideoMP4         = "video_mp4"
	CapabilityQueryText        = "query_text"
	CapabilityQueryImageJPEG   = "query_image_jpeg"
	CapabilityQueryImagePNG    = "query_image_png"
	CapabilityQueryImageWebP   = "query_image_webp"
	CapabilityQueryImageGIF    = "query_image_gif"
	CapabilityQueryTextImage   = "query_text_image"

	CapabilityInterleavedJPEG        = "interleaved_text_jpeg"
	CapabilityInterleavedPNG         = "interleaved_text_png"
	CapabilityInterleavedWebP        = "interleaved_text_webp"
	CapabilityInterleavedGIFStill    = "interleaved_text_gif"
	CapabilityInterleavedGIFAnimated = "interleaved_text_gif_animated"
	CapabilityInterleavedMP4         = "interleaved_text_mp4"

	CapabilityBatchLimits = "batch_limits"
)

Capability identifiers, in manifest order.

View Source 
const (
	// DefaultTimeout bounds one provider request attempt.
	DefaultTimeout = 45 * time.Second
	// MaxTimeout is the largest per-attempt timeout accepted by NewClient.
	MaxTimeout = 5 * time.Minute
	// DefaultMaxRetries is the default attempt count for retryable failures.
	DefaultMaxRetries = 3
	// MaxRetries is the largest attempt count accepted by NewClient.
	MaxRetries = 10
)
View Source 
const (
	FixtureJPEG        = "image_jpeg.jpg"
	FixturePNG         = "image_png.png"
	FixtureWebP        = "image_webp.webp"
	FixtureGIFStill    = "image_gif_still.gif"
	FixtureGIFAnimated = "image_gif_animated.gif"
	FixtureMP4         = "video_mp4.mp4"

	// FixtureJPEGAlt and the other variant fixtures contrast their primary:
	// each interleaved probe swaps its media between a fixture and its
	// variant so pixel contribution is demonstrated within the format, never
	// across formats.
	FixtureJPEGAlt        = "image_jpeg_alt.jpg"
	FixtureWebPAlt        = "image_webp_alt.webp"
	FixtureGIFStillAlt    = "image_gif_still_alt.gif"
	FixtureGIFAnimatedAlt = "image_gif_animated_alt.gif"
	FixtureMP4Alt         = "video_mp4_alt.mp4"

	FixtureRed  = "probe_red.png"
	FixtureBlue = "probe_blue.png"

	// ProbeQueryText is the text query the probe ranks against the red and
	// blue reference documents.
	ProbeQueryText = "a solid red square"
	// ProbeBlueText is the opposing text used to prove that composite inputs
	// consume their text part independently of their media part.
	ProbeBlueText = "a solid blue square"
	// ProbeInterleavedText is the text part of the interleaved probe document.
	ProbeInterleavedText = "a solid red square"
)

Fixture file names inside a probe fixture directory.

View Source 
const (
	// CapabilitySchemaVersion is the manifest schema this package reads and
	// writes.
	CapabilitySchemaVersion = 2
	// ProbeFixtureContract identifies the deterministic fixtures and evidence
	// checks a probe must have used. v3 added contrasting same-format
	// variants and full-format batch coverage.
	ProbeFixtureContract = 3
)
View Source 
const (
	ReasonProviderRejected    = "provider_rejected"
	ReasonProviderLimit       = "provider_limit"
	ReasonMalformedResponse   = "malformed_response"
	ReasonTransientExhausted  = "transient_exhausted"
	ReasonMotionNotObserved   = "motion_not_observed"
	ReasonRankingNotObserved  = "ranking_not_observed"
	ReasonOrderNotObserved    = "order_not_observed"
	ReasonInvalidOrLocalError = "invalid_or_local_failure"
)

Sanitized reason codes for non-passing probe results.

View Source 
const (

	// DefaultEndpoint is the package-pinned Voyage API root.
	DefaultEndpoint = "https://api.voyageai.com/v1"
	// DefaultModel is the package-pinned multimodal embedding model.
	DefaultModel = "voyage-multimodal-3.5"
	// DefaultDimension is the pinned output dimension for DefaultModel.
	DefaultDimension = 1024
	// MaxBatchItems is the largest document batch accepted by Policy.
	MaxBatchItems = 64
	// MaxRequestBytes is the largest encoded request accepted by Policy.
	MaxRequestBytes = int64(64 << 20)
	// MaxResponseBytes is the largest provider response accepted by Policy.
	MaxResponseBytes = int64(8 << 20)
)

Variables

View Source 
var (
	// ErrUnauthorized marks a provider 401 or 403; the credential, not the
	// input, is wrong.
	ErrUnauthorized = errors.New("voyage embedding authorization failed")
	// ErrBatchTooLarge marks a request refused locally by policy limits or by
	// the provider for size; splitting the batch may succeed.
	ErrBatchTooLarge = errors.New("voyage embedding request too large")
	// ErrPermanentResponse marks a provider 4xx other than rate limiting,
	// authorization, or size.
	ErrPermanentResponse = errors.New("voyage embedding permanent response")
	// ErrTransientResponse marks an exhausted retryable provider or transport
	// failure.
	ErrTransientResponse = errors.New("voyage embedding transient response")
	// ErrMalformedResponse marks a provider response that could not be
	// validated; it is retried once because it may be transient corruption.
	ErrMalformedResponse = errors.New("voyage embedding malformed response")
	// ErrCapabilityContract marks input that no supplied authorization covers.
	ErrCapabilityContract = errors.New("voyage embedding input lacks capability authorization")
	// ErrInvalidInput marks input that violates the request shape or the
	// policy media bounds before any request is made.
	ErrInvalidInput = errors.New("voyage embedding input is invalid")
)
View Source 
var SeedFixtureNames = []string{FixtureWebP, FixtureWebPAlt, FixtureMP4, FixtureMP4Alt}

SeedFixtureNames lists the fixtures an operator must supply as synthetic seeds because the Go standard library cannot encode them.

Functions

func EncodeCapabilityManifest 

func EncodeCapabilityManifest(writer io.Writer, manifest CapabilityManifest) error

EncodeCapabilityManifest writes an indented, validated manifest.

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable reports whether err is a transient provider or transport failure an application can schedule again later.

func RetryAfter 

func RetryAfter(err error) (time.Duration, bool)

RetryAfter returns the provider's Retry-After delay when the failure carried one.

func ValidateProbeFixtures 

func ValidateProbeFixtures(ctx context.Context, policy Policy, config ProbeFixtureConfig) error

ValidateProbeFixtures verifies a complete fixture set locally: every file is present, detects as its expected format, matches its deterministic generation where applicable, and is eligible under the policy media bounds. It performs no network access.

func WriteProbeFixtures 

func WriteProbeFixtures(ctx context.Context, destination string, options FixtureOptions) (err error)

WriteProbeFixtures writes the deterministic fixture set into destination. The destination must not exist, and its parent and the seed directory must already be owner-private. A complete set is published from private staging.

Types

type Authorization 

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

Authorization is opaque evidence that one capability passed an authenticated probe under a policy. It does not attest human consent.

func (Authorization) Capability 

func (a Authorization) Capability() Capability

Capability returns the authorized capability.

func (Authorization) PolicyFingerprint 

func (a Authorization) PolicyFingerprint() string

PolicyFingerprint returns the public policy identity covered by the authorization.

type Capability 

type Capability struct {
	// ID is the stable capability identifier.
	ID string
	// Kind groups the capability.
	Kind CapabilityKind
	// Format is the media format covered by the probe, when applicable.
	Format media.Format
	// Animated marks the animated-image capability.
	Animated bool
	// InputType is the provider input type used by the probe request.
	InputType string
	// Description explains what a passing probe demonstrates.
	Description string
}

Capability describes one probe-tested provider capability.

func Capabilities 

func Capabilities() []Capability

Capabilities returns every capability in manifest order.

func CapabilityByID 

func CapabilityByID(id string) (Capability, bool)

CapabilityByID returns the capability with the given identifier.

type CapabilityKind 

type CapabilityKind string

CapabilityKind groups capabilities by how they are probed and consumed. 

const (
	// CapabilityKindDocument authorizes one media format as document input.
	CapabilityKindDocument CapabilityKind = "document"
	// CapabilityKindQuery authorizes one query input mode.
	CapabilityKindQuery CapabilityKind = "query"
	// CapabilityKindRequest authorizes a request shape rather than a format.
	CapabilityKindRequest CapabilityKind = "request"
)

Capability kinds.

type CapabilityManifest 

type CapabilityManifest struct {
	SchemaVersion        int                `json:"schema_version"`
	ProbeFixtureContract int                `json:"probe_fixture_contract"`
	ObservedOn           string             `json:"observed_on"`
	Endpoint             string             `json:"endpoint"`
	Model                string             `json:"model"`
	Dimension            int                `json:"dimension"`
	MaxBatchItems        int                `json:"max_batch_items"`
	Results              []CapabilityResult `json:"results"`
}

CapabilityManifest contains sanitized, operator-produced evidence from an authenticated capability probe. It contains no media, vectors, or secrets.

func DecodeCapabilityManifest 

func DecodeCapabilityManifest(reader io.Reader) (CapabilityManifest, error)

DecodeCapabilityManifest strictly decodes a bounded manifest.

func RunCapabilityProbe 

func RunCapabilityProbe(ctx context.Context, client *Client, config ProbeConfig) (CapabilityManifest, error)

RunCapabilityProbe probes every capability serially against the live provider and returns sanitized observations only. An authorization failure aborts the probe because nothing can pass without a valid credential.

func (CapabilityManifest) ValidateComplete 

func (m CapabilityManifest) ValidateComplete() error

ValidateComplete validates a complete manifest without performing network access.

type CapabilityResult 

type CapabilityResult struct {
	CapabilityID       string      `json:"capability_id"`
	Status             ProbeStatus `json:"status"`
	ReasonCode         string      `json:"reason_code,omitzero"`
	FixtureDigest      string      `json:"fixture_digest"`
	RequestFingerprint string      `json:"request_fingerprint"`
	TotalTokens        *int64      `json:"total_tokens,omitempty"`
}

CapabilityResult contains sanitized observations for one capability.

type Client 

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

Client calls the single endpoint derived from its policy.

func NewClient 

func NewClient(policy Policy, config ClientConfig) (*Client, error)

NewClient validates operational bounds without making a network request.

func (*Client) EmbedDocuments 

func (c *Client) EmbedDocuments(ctx context.Context, inputs []Input, authorizations []Authorization) (Result, error)

EmbedDocuments embeds a batch of documents. Every media part must be covered by an authorization from this client's policy; a batch of more than one input is limited to media-only PNG documents and requires the batch capability. Text-then-media is limited to PNG and requires the interleaved capability.

func (*Client) EmbedQuery 

func (c *Client) EmbedQuery(ctx context.Context, input Input, authorizations ...Authorization) ([]float32, Usage, error)

EmbedQuery embeds one query shaped [text], image, or [text, image]. Text needs the text-query capability, an image needs the query capability for its own format, and the combined shape is limited to PNG and also needs the text-and-image capability.

func (*Client) Policy 

func (c *Client) Policy() Policy

Policy returns the policy the client was built with.

type ClientConfig 

type ClientConfig struct {
	APIKey         string
	Timeout        time.Duration
	MaxRetries     int
	RetryBaseDelay time.Duration
	HTTPClient     *http.Client
}

ClientConfig contains bounded operational settings outside policy identity.

type FixtureOptions 

type FixtureOptions struct {
	// SeedDirectory holds operator-supplied synthetic WebP and MP4 seeds
	// named as in SeedFixtureNames. Required.
	SeedDirectory string
}

FixtureOptions controls probe fixture generation.

type Input 

type Input struct {
	Parts []Part
}

Input is one document or query: ordered parts with at most one media part.

type Media 

type Media struct {
	Metadata media.Metadata
	Bytes    []byte
}

Media is one media part: detected metadata and the bytes it describes.

type Part 

type Part struct {
	Text  string
	Media *Media
}

Part is one ordered element of an input: text or media, never both.

type Policy 

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

Policy is an opaque reusable Voyage processing policy.

func NewPolicy 

func NewPolicy(config PolicyConfig) (Policy, error)

NewPolicy validates and constructs an immutable policy.

func (Policy) Authorize 

func (p Policy) Authorize(manifest CapabilityManifest, capabilityID string) (Authorization, error)

Authorize derives non-persistable capability authority from a complete manifest.

func (Policy) AuthorizeAll 

func (p Policy) AuthorizeAll(manifest CapabilityManifest) ([]Authorization, error)

AuthorizeAll returns an authorization for every capability the manifest passes under this policy. It never fails for unauthorized capabilities; it omits them.

func (Policy) CanonicalJSON 

func (p Policy) CanonicalJSON(manifest CapabilityManifest) ([]byte, error)

CanonicalJSON returns the canonical reusable policy identity, including the capabilities the manifest authorizes under this policy.

func (Policy) Fingerprint 

func (p Policy) Fingerprint(manifest CapabilityManifest) (string, error)

Fingerprint returns lowercase SHA-256 over CanonicalJSON.

func (Policy) MediaPolicy 

func (p Policy) MediaPolicy() media.Policy

MediaPolicy returns the media bounds covered by this policy's identity.

func (Policy) Values 

func (p Policy) Values() PolicyValues

Values returns a copy of every effective policy value.

type PolicyConfig 

type PolicyConfig struct {
	// Model must be a package-pinned model; empty selects DefaultModel.
	Model string
	// Dimension must be the pinned dimension for Model; zero selects it.
	Dimension int
	// Media bounds document and query media.
	Media media.Policy
	// MaxBatchItems bounds one document request; zero selects MaxBatchItems.
	MaxBatchItems int
	// MaxRequestBytes bounds one encoded request; zero selects MaxRequestBytes.
	MaxRequestBytes int64
	// MaxResponseBytes bounds one provider response; zero selects MaxResponseBytes.
	MaxResponseBytes int64
}

PolicyConfig contains reusable processing policy.

type PolicyValues 

type PolicyValues struct {
	Provider         string       `json:"provider"`
	Endpoint         string       `json:"endpoint"`
	Model            string       `json:"model"`
	Dimension        int          `json:"dimension"`
	Media            media.Policy `json:"media"`
	MaxBatchItems    int          `json:"max_batch_items"`
	MaxRequestBytes  int64        `json:"max_request_bytes"`
	MaxResponseBytes int64        `json:"max_response_bytes"`
}

PolicyValues is a read-only copy of every effective policy value.

type ProbeConfig 

type ProbeConfig struct {
	Fixtures   ProbeFixtureConfig
	ObservedAt time.Time
}

ProbeConfig controls one explicit authenticated capability probe.

type ProbeFixtureConfig 

type ProbeFixtureConfig struct {
	FixtureDirectory string
}

ProbeFixtureConfig locates a written fixture set.

type ProbeStatus 

type ProbeStatus string

ProbeStatus describes the result of one authenticated capability probe. 

const (
	ProbeStatusPassed   ProbeStatus = "passed"
	ProbeStatusRejected ProbeStatus = "provider_rejected"
	ProbeStatusFailed   ProbeStatus = "probe_failed"
)

Probe statuses.

type ProviderError 

type ProviderError struct {
	Kind       error
	StatusCode int
	RetryAfter time.Duration
	RetrySet   bool
	Metrics    RequestMetrics
	// contains filtered or unexported fields
}

ProviderError carries the classification and accounting for a failed request. Error strings never include provider response bodies.

func (*ProviderError) Error 

func (e *ProviderError) Error() string

func (*ProviderError) Unwrap 

func (e *ProviderError) Unwrap() []error

Unwrap exposes the kind and, when present, the transport cause.

type RequestMetrics 

type RequestMetrics struct {
	Requests int
	Retries  int
	Latency  time.Duration
}

RequestMetrics describes actual provider HTTP work for one logical request.

func MetricsFromError 

func MetricsFromError(err error) RequestMetrics

MetricsFromError recovers provider request accounting from an embedding error.

type Result 

type Result struct {
	Vectors [][]float32
	Usage   Usage
	Metrics RequestMetrics
}

Result contains one vector per input, in input order, plus accounting.

type Usage 

type Usage struct {
	TotalTokens int64
	Available   bool
}

Usage reports provider token accounting when the provider returned it.

Source Files

View all Source files

Directories

Path Synopsis
internal
probecontract
Package probecontract pins the request identity shared by the Voyage capability probe and synthetic test manifests.
 Package probecontract pins the request identity shared by the Voyage capability probe and synthetic test manifests.
Package voyagetest provides synthetic capability evidence for applications that test Voyage integrations.
 Package voyagetest provides synthetic capability evidence for applications that test Voyage integrations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.