steady

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 28, 2026 License: MIT Imports: 20 Imported by: 0

README

SteadyPicker

SteadyPicker is a local, deterministic video-settings engine. It chooses a quota-aware duration and parses aspect ratio and resolution without making a network or LLM call in production.

The CLI embeds an artifact, attribution, and the quota-safe-v2 profile. A single executable is enough.

v0.2: the embedded long-only model enables learned six-second decisions and disables learned shortening. Its frozen sealed evaluation accepted 8 examples, all 8 correct. Full metrics and limitations are published in evaluation/README.md.

Quick start

go install github.com/hensmth/steady-picker/cmd/steady-picker@latest

printf '%s\n' \
  '{"prompt":"a flower progresses from bud to full bloom","mode":"text-to-video"}' |
  steady-picker predict --profile quota-safe-v2

predict accepts newline-delimited JSON exclusively through stdin, so prompts do not appear in process arguments. It emits one result per input line:

{
  "duration": 4,
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "source": "fallback",
  "duration_source": "fallback",
  "aspect_ratio_source": "fallback",
  "resolution_source": "fallback",
  "confidence": 0,
  "model_version": "settings-v2",
  "policy_version": "quota-safe-v2",
  "profile_version": "2",
  "artifact_sha256": "...",
  "reasons": ["duration.safe_fallback", "aspect.safe_fallback", "resolution.safe_fallback"],
  "estimated_cost_microusd": 200000,
  "pricing_as_of": "2026-07-28"
}

Ready-to-run Linux, macOS, and Windows binaries are attached to each release. Verify them with SHA256SUMS and GitHub artifact attestations before use.

Policy profiles

Provider capabilities and application budgets are separate. A Profile defines allowed durations, semantic mappings, resolutions, aspect ratios, defaults, maximums, and optional per-second price estimates.

The embedded quota-safe-v2 profile:

  • maps semantic short, medium, and long labels to 2, 4, and 6 seconds;
  • defaults to 4 seconds, 480p, and 16:9 for text-to-video;
  • permits an explicit 720p request;
  • preserves source aspect ratio for image-to-video by default; and
  • estimates 480p at 50,000 micro-USD/sec and 720p at 70,000 micro-USD/sec, with a dated pricing field.

Decision precedence is field-specific: valid explicit request, source-media constraint, accepted learned duration, then safe fallback. The pragmatic decision policy accepts only learned long decisions. Explicit 2-second requests still work. The model never controls aspect ratio or resolution.

Use a custom governed profile:

steady-picker predict --profile-file ./profile.json < requests.jsonl

Input

{
  "prompt": "one quick wink in a portrait frame",
  "mode": "text-to-video",
  "duration": 2,
  "aspect_ratio": "9:16",
  "resolution": "480p"
}

mode is text-to-video or image-to-video. Image requests may provide source_media_aspect_ratio; the v0.1 image_aspect_ratio number remains accepted for compatibility. Prompts must be valid UTF-8, non-empty, and no larger than 16 KiB.

Technical prompt cues are negation- and conflict-aware. Unsupported durations round upward to the next profile duration and values above the maximum clamp. Conflicting affirmative cues use the safe fallback.

Operations

steady-picker health
steady-picker inspect-model
steady-picker licenses
steady-picker predict --model ./custom-v3.bin < requests.jsonl

Artifact v5 contains the compact semantic model and decision-policy marker; v3 and v4 remain loadable. Models over 64 MiB, malformed dimensions, non-finite values, unknown labels, or ambiguous v2 label order are rejected before inference. Use v0.1 for a legacy v2 artifact or retrain it.

Go library

model, err := steady.LoadDefault()
if err != nil {
    log.Fatal(err)
}
result, err := steady.PickSettings(
    model,
    steady.QuotaSafeProfile(),
    steady.PickRequest{
        Prompt: "a person walks naturally across a room",
        Mode: steady.TextToVideo,
    },
)

Public entry points are Load, LoadBytes, LoadDefault, Model.Metadata, NewProfile, QuotaSafeProfile, and PickSettings. Loaded models are immutable and safe for concurrent use; no Close call is needed. Returned classification slices are caller-owned.

Reproducible training

The semantic pipeline uses a governed 14,000-row development corpus and a separate 1,000-row sealed holdout. Three blind structured teacher votes label each prompt; disagreement means safe fallback. Near-duplicate clusters remain together across splits.

The student is a deterministic, quantized two-layer Transformer with separate short and long heads. The frozen pragmatic candidate uses learning rate 0.0007, long-class weight 0.75, contrastive weight 0.25, and focal strength 1.0. The public runbook contains the exact corpus, labelling, selection, evaluation, and engineering commands: docs/SEMANTIC_RETRAINING.md.

The locked test, FETV evaluation, and independent AI-adjudicated audit are opened only after temperature, conformal quantiles, and policy thresholds are frozen. See MODEL_CARD.md, the corpus dataset card, and the full methodology.

Development

go test ./...
go test -race ./...
go vet ./...
govulncheck ./...
go test -run '^$' -bench BenchmarkPickSettingsFallback -benchmem

CI also runs CodeQL and dependency review on Linux, macOS, and Windows. Release automation verifies the exact embedded model and its checked-in evaluation evidence before creating a draft.

License

Source code is MIT. The published v2 corpus and model are CC-BY-4.0. VideoUFO attribution and DiffusionDB/FETV notices are embedded and available through steady-picker licenses. See THIRD_PARTY_NOTICES.md.

Documentation

Overview

Package steady provides local, quota-aware video setting selection in pure Go.

Models use strict, provenance-carrying v3 artifacts and are safe for concurrent use. Duration is learned; aspect ratio and resolution remain deterministic. 

m, err := steady.LoadDefault()
if err != nil { /* handle error */ }
result, err := steady.PickSettings(m, steady.QuotaSafeProfile(), steady.PickRequest{
	Prompt: "a flower transforms through three ordered stages",
	Mode: steady.TextToVideo,
})

Index

Constants

View Source 
const DecisionPolicyLongOnlyPragmaticV2 = "long-only-pragmatic-v2"
View Source 
const DefaultModelVersion = "settings-v2"

DefaultModelVersion identifies the embedded artifact interface.

View Source 
const (
	ProfileQuotaSafeV2 = "quota-safe-v2"
)

Variables

This section is empty.

Functions

func Licenses added in v0.2.0 

func Licenses() string

Licenses returns the attribution and third-party notices embedded in the standalone library and CLI.

func Train 

func Train(cfg TrainConfig) error

Train fits the v4 class-balanced dual-head sparse model.

Types

type DebugResult 

type DebugResult struct {
	Logits        []float32 `json:"logits"`
	Probabilities []float32 `json:"probabilities"`
	Quantiles     []float32 `json:"quantiles"`
	Thresholds    []float32 `json:"thresholds"`
	Kinds         []string  `json:"kinds"`
	IsEmpty       bool      `json:"is_empty"`
}

DebugResult contains caller-owned intermediate inference values.

type Metadata added in v0.2.0 

type Metadata struct {
	ArtifactFormat       int       `json:"artifact_format"`
	ModelID              string    `json:"model_id"`
	Task                 string    `json:"task"`
	Labels               []string  `json:"labels"`
	PolicyCompatibility  string    `json:"policy_compatibility"`
	MinN                 int       `json:"min_ngram"`
	MaxN                 int       `json:"max_ngram"`
	Bucket               int       `json:"bucket"`
	Dimension            int       `json:"dimension"`
	Epochs               int       `json:"epochs"`
	LearningRate         float64   `json:"learning_rate"`
	L2                   float64   `json:"l2"`
	Alpha                float64   `json:"alpha"`
	Seed                 uint64    `json:"seed"`
	SourceManifestSHA256 string    `json:"source_manifest_sha256"`
	TrainingCodeCommit   string    `json:"training_code_commit"`
	ArtifactSHA256       string    `json:"artifact_sha256,omitempty"`
	ModelFamily          string    `json:"model_family,omitempty"`
	FeatureSchema        string    `json:"feature_schema,omitempty"`
	Heads                []string  `json:"heads,omitempty"`
	WordMinN             int       `json:"word_min_ngram,omitempty"`
	WordMaxN             int       `json:"word_max_ngram,omitempty"`
	TemporalFeatures     int       `json:"temporal_features,omitempty"`
	PositiveClassWeights []float64 `json:"positive_class_weights,omitempty"`
	Tokenizer            string    `json:"tokenizer,omitempty"`
	Vocabulary           []string  `json:"vocabulary,omitempty"`
	MaxTokens            int       `json:"max_tokens,omitempty"`
	Layers               int       `json:"layers,omitempty"`
	AttentionHeads       int       `json:"attention_heads,omitempty"`
	HiddenSize           int       `json:"hidden_size,omitempty"`
	IntermediateSize     int       `json:"intermediate_size,omitempty"`
	Quantization         string    `json:"quantization,omitempty"`
	AuxiliaryHeads       []string  `json:"auxiliary_heads,omitempty"`
	TeacherEncoder       string    `json:"teacher_encoder,omitempty"`
	TrainingProvider     string    `json:"training_provider,omitempty"`
	TrainingModel        string    `json:"training_model,omitempty"`
	TrainingEffort       string    `json:"training_effort,omitempty"`
	TrainingBackend      string    `json:"training_backend,omitempty"`
	TrainingToolchain    string    `json:"training_toolchain,omitempty"`
	DecisionPolicy       string    `json:"decision_policy,omitempty"`
}

Metadata is the canonical, immutable provenance carried by an artifact.

type Mode added in v0.2.0 

type Mode string
const (
	TextToVideo  Mode = "text-to-video"
	ImageToVideo Mode = "image-to-video"
)

type Model 

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

Model contains immutable model weights and a pool of independent workspaces. It is safe for concurrent use and has no lifecycle-dependent Close method.

func Load 

func Load(path string) (*Model, error)

Load reads a strict v3, v4, or v5 artifact from path.

func LoadBytes 

func LoadBytes(input []byte) (*Model, error)

LoadBytes parses a strict v3, v4, or v5 artifact and copies all model data.

func LoadDefault 

func LoadDefault() (*Model, error)

LoadDefault loads the embedded immutable artifact. Development builds may contain the self-contained settings-v2 semantic artifact.

func (*Model) Classify 

func (m *Model) Classify(text string) PredictionSet

Classify returns an owned prediction set and is safe for concurrent use.

func (*Model) ClassifyDebug 

func (m *Model) ClassifyDebug(text string) DebugResult

ClassifyDebug is safe for concurrent use.

func (*Model) Metadata added in v0.2.0 

func (m *Model) Metadata() Metadata

Metadata returns a caller-owned copy of the artifact metadata.

type PickRequest 

type PickRequest struct {
	Prompt                 string  `json:"prompt"`
	Mode                   Mode    `json:"mode"`
	Duration               int     `json:"duration,omitempty"`
	AspectRatio            string  `json:"aspect_ratio,omitempty"`
	Resolution             string  `json:"resolution,omitempty"`
	SourceMediaAspectRatio string  `json:"source_media_aspect_ratio,omitempty"`
	ImageAspectRatio       float64 `json:"image_aspect_ratio,omitempty"` // v0.1 compatibility
}

type PickResult 

type PickResult struct {
	Duration              int     `json:"duration"`
	AspectRatio           string  `json:"aspect_ratio"`
	Resolution            string  `json:"resolution"`
	Source                string  `json:"source"`
	DurationSource        string  `json:"duration_source"`
	AspectRatioSource     string  `json:"aspect_ratio_source"`
	ResolutionSource      string  `json:"resolution_source"`
	Confidence            float32 `json:"confidence"`
	ModelVersion          string  `json:"model_version"`
	PolicyVersion         string  `json:"policy_version"`
	ProfileVersion        string  `json:"profile_version"`
	ArtifactSHA256        string  `json:"artifact_sha256"`
	Reasons               Reasons `json:"reasons"`
	EstimatedCostMicroUSD int64   `json:"estimated_cost_microusd"`
	PricingAsOf           string  `json:"pricing_as_of,omitempty"`
}

func PickSettings 

func PickSettings(model *Model, profile Profile, request PickRequest) (PickResult, error)

type PredictionSet 

type PredictionSet struct {
	Kinds         []string  `json:"kinds"`
	Probabilities []float32 `json:"probabilities"`
}

PredictionSet is an owned, immutable prediction result.

func (PredictionSet) IsEmpty 

func (p PredictionSet) IsEmpty() bool

type PriceEstimate added in v0.2.0 

type PriceEstimate struct {
	Resolution   string `json:"resolution"`
	MicroUSDPerS int64  `json:"microusd_per_second"`
}

type Profile added in v0.2.0 

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

func NewProfile added in v0.2.0 

func NewProfile(config ProfileConfig) (Profile, error)

func QuotaSafeProfile added in v0.2.0 

func QuotaSafeProfile() Profile

type ProfileConfig added in v0.2.0 

type ProfileConfig struct {
	Name               string            `json:"name"`
	Version            string            `json:"version"`
	AllowedDurations   []int             `json:"allowed_durations"`
	SemanticDurations  map[string]int    `json:"semantic_durations"`
	AllowedResolutions []string          `json:"allowed_resolutions"`
	AllowedAspects     []string          `json:"allowed_aspect_ratios"`
	DefaultDuration    int               `json:"default_duration"`
	MaximumDuration    int               `json:"maximum_duration"`
	DefaultResolution  string            `json:"default_resolution"`
	DefaultTextAspect  string            `json:"default_text_aspect_ratio"`
	PricingAsOf        string            `json:"pricing_as_of,omitempty"`
	Prices             []PriceEstimate   `json:"prices,omitempty"`
	Metadata           map[string]string `json:"metadata,omitempty"`
}

type Reasons added in v0.2.0 

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

Reasons is a small caller-owned value list with JSON-array encoding.

func (Reasons) MarshalJSON added in v0.2.0 

func (r Reasons) MarshalJSON() ([]byte, error)

func (Reasons) Strings added in v0.2.0 

func (r Reasons) Strings() []string

Strings returns a caller-owned slice.

func (*Reasons) UnmarshalJSON added in v0.2.0 

func (r *Reasons) UnmarshalJSON(data []byte) error

type TrainConfig 

type TrainConfig struct {
	TrainInput                  string
	ProbabilityCalibrationInput string
	ConformalCalibrationInput   string
	ThresholdDevelopmentInput   string
	Output                      string
	Bucket                      int
	Dimension                   int
	MinN                        int
	MaxN                        int
	Epochs                      int
	LearningRate                float32
	L2                          float32
	Alpha                       float64
	Seed                        uint64
	SourceManifestSHA256        string
	TrainingCodeCommit          string
	PositiveWeightScale         float32
}

TrainConfig describes a deterministic, single-threaded v3 training run. All four datasets must have been frozen before training.

func DefaultTrainConfig 

func DefaultTrainConfig() TrainConfig

Source Files

View all Source files

Directories

Path Synopsis
cmd
steady-parity command
Command steady-parity exposes raw classifier probabilities for parity checks.
 Command steady-parity exposes raw classifier probabilities for parity checks.
steady-picker command

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.