promptcache

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package promptcache defines the provider-neutral host/plugin contract for prompt-cache residency. It deliberately contains no provider wire types, cache-key schema, request replay shape, or scheduling policy.

Index

Constants

View Source
const (
	MaxTargetIDBytes      = 256
	MaxGenerationIDBytes  = 256
	MaxHandleBytes        = 256
	MaxOperationIDBytes   = 256
	MaxLegIDBytes         = 256
	MaxObservationsPerLeg = 16
	MaxLifecycleKinds     = 5
)
View Source
const MaxAccountingDedupeKeyBytes = 256

Variables

View Source
var (
	ErrInvalid            = errors.New("promptcache: invalid contract value")
	ErrOversized          = errors.New("promptcache: value exceeds bound")
	ErrUnknownLifecycle   = errors.New("promptcache: unknown lifecycle")
	ErrHandleRequired     = errors.New("promptcache: renewable observation requires a handle")
	ErrControlUnsupported = errors.New("promptcache: control unsupported")
	ErrStaleHandle        = errors.New("promptcache: stale handle")
)

Functions

func WithObservationLineage

func WithObservationLineage(ctx context.Context, lineage ObservationLineage) context.Context

Types

type AccountingAuthority

type AccountingAuthority string
const (
	AccountingAuthorityAuthoritative AccountingAuthority = "authoritative"
	AccountingAuthorityEstimated     AccountingAuthority = "estimated"
	AccountingAuthorityDelegated     AccountingAuthority = "delegated"
	AccountingAuthorityAdvisory      AccountingAuthority = "advisory"
)

type AccountingEvidence

type AccountingEvidence struct {
	InputTokens      *int64
	OutputTokens     *int64
	CacheReadTokens  *int64
	CacheWriteTokens *int64
	ReasoningTokens  *int64
	TotalTokens      *int64
	Presence         lipapi.UsagePresence
	Source           AccountingSource
	Authority        AccountingAuthority
	Plane            AccountingPlane
	DedupeKey        string
}

func (AccountingEvidence) Validate

func (e AccountingEvidence) Validate() error

type AccountingPlane

type AccountingPlane string
const AccountingPlaneProviderBillable AccountingPlane = "provider_billable"

type AccountingSource

type AccountingSource string
const (
	AccountingSourceProviderReported AccountingSource = "provider_reported"
	AccountingSourceProviderCountAPI AccountingSource = "provider_count_api"
	AccountingSourceLocalEstimator   AccountingSource = "local_estimator"
	AccountingSourceLocalTokenizer   AccountingSource = "local_tokenizer"
)

type CacheEvidence

type CacheEvidence struct {
	InputTokens      *int64
	OutputTokens     *int64
	CacheReadTokens  *int64
	CacheWriteTokens *int64
	TotalTokens      *int64
}

func (CacheEvidence) Validate

func (e CacheEvidence) Validate() error

type Controller

type Controller interface {
	Renew(context.Context, RenewRequest) (RenewResponse, error)
	Release(context.Context, ReleaseRequest) error
}

type GenerationID

type GenerationID string

func (GenerationID) Validate

func (id GenerationID) Validate(required bool) error

type Handle

type Handle []byte

func (Handle) Validate

func (h Handle) Validate(required bool) error

type LifecycleKind

type LifecycleKind string
const (
	LifecycleUnknown          LifecycleKind = "unknown"
	LifecycleSlidingExpiry    LifecycleKind = "sliding_expiry"
	LifecycleFixedExpiry      LifecycleKind = "fixed_expiry"
	LifecycleMinimumResidency LifecycleKind = "minimum_residency"
	LifecycleBestEffort       LifecycleKind = "best_effort"
)

func (LifecycleKind) Validate

func (k LifecycleKind) Validate() error

type Observation

type Observation struct {
	ALegID            string
	BLegID            string
	BackendInstanceID string
	TargetID          TargetID
	GenerationID      GenerationID
	Lifecycle         LifecycleKind
	Timing            Timing
	Renewable         bool
	Handle            Handle
	Evidence          CacheEvidence
}

func (Observation) Validate

func (o Observation) Validate() error

type ObservationBuffer

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

func (*ObservationBuffer) Add

func (*ObservationBuffer) Commit

func (b *ObservationBuffer) Commit()

func (*ObservationBuffer) Discard

func (b *ObservationBuffer) Discard()

func (*ObservationBuffer) DrainPromptCacheObservations

func (b *ObservationBuffer) DrainPromptCacheObservations() []Observation

type ObservationLineage

type ObservationLineage struct {
	ALegID            string
	BLegID            string
	BackendInstanceID string
	CanonicalModelID  string
}

ObservationLineage carries only bounded routing/session attribution needed by a provider adapter to associate a foreground observation with its B-leg. It is not a cache identity or a scheduling key.

func ObservationLineageFromContext

func ObservationLineageFromContext(ctx context.Context) (ObservationLineage, bool)

type ObservationSource

type ObservationSource interface{ DrainPromptCacheObservations() []Observation }

type Profile

type Profile struct {
	ObservationSupported bool
	RenewalSupported     bool
	LifecycleKinds       []LifecycleKind
}

func (Profile) Normalize

func (p Profile) Normalize() (Profile, error)

func (Profile) Validate

func (p Profile) Validate() error

type ReleaseRequest

type ReleaseRequest struct{ Handle Handle }

func (ReleaseRequest) Validate

func (r ReleaseRequest) Validate() error

type RenewRequest

type RenewRequest struct {
	Handle      Handle
	OperationID string
}

func (RenewRequest) Validate

func (r RenewRequest) Validate() error

type RenewResponse

type RenewResponse struct {
	Result     RenewResult
	Accounting *AccountingEvidence
}

func (RenewResponse) Validate

func (r RenewResponse) Validate() error

type RenewResult

type RenewResult struct {
	Status      RenewStatus
	Observation *Observation
	Evidence    CacheEvidence
}

func (RenewResult) Validate

func (r RenewResult) Validate() error

type RenewStatus

type RenewStatus string
const (
	Renewed       RenewStatus = "renewed"
	StillResident RenewStatus = "still_resident"
	ColdRecreated RenewStatus = "cold_recreated"
	Stale         RenewStatus = "stale"
	Unsupported   RenewStatus = "unsupported"
	ControlFailed RenewStatus = "control_failed"
)

func (RenewStatus) Validate

func (s RenewStatus) Validate() error

type TargetID

type TargetID string

func (TargetID) Validate

func (id TargetID) Validate(required bool) error

type Timing

type Timing struct {
	ObservedAt           time.Time
	ExpiresAt            *time.Time
	MinimumResidentUntil *time.Time
}

func (Timing) Validate

func (t Timing) Validate() error

Jump to

Keyboard shortcuts

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