avatar

Documentation

Overview

Package avatar resolves the named avatar registry (config `avatars.*`) and composes per-panel image prompts for the "actor" capability: a recurring character (the author, later co-authors) composited into reel panels via image-to-image, reacting to each beat.

The model keeps three concerns independent (spec 0006 §2):

• likeness (who) — from the avatar profile; theme-independent.
• style (how) — the avatar's OWN captured style by default, or the active theme's style when restyling. NEVER hardcoded into the likeness (the blog experiment's risograph mistake).
• direction (what) — the per-panel card scene (pose + prop + gaze + emotion).

keryx holds no avatar asset; Ref is resolved relative to the owning project.

Index

• Constants
• Variables
• func Compose(cast []Named, scene, themeStyle string) string
• type Avatar
  • func Analyse(ctx context.Context, d Describer, image provider.RefImage) (Avatar, error)
  • func Resolve(r config.Reader, name string) (Avatar, error)
  • func (a Avatar) Prompt(scene, themeStyle string) string
• type Describer
• type Named

Constants

const AnalysisPrompt = "Analyse the person in this image so they can be re-drawn consistently in " +
	"illustrations. Reply with JSON only (no prose), keys: " +
	`"likeness" (a concise physical description — hair, beard, build, skin, distinguishing ` +
	`features; no clothing), "style" (the art style of THIS image, e.g. "flat screen-print / ` +
	`risograph illustration", "3D clay render", "photographic"), "palette" (the dominant ` +
	`colours). Example: {"likeness":"…","style":"…","palette":"…"}.`

AnalysisPrompt steers the first-use vision analysis (spec 0006 §2). It asks for a reusable profile, keeping likeness style-independent so the avatar can be restyled into any theme.

const AnalyzeTimeout = 120 * time.Second

AnalyzeTimeout bounds a single first-use analysis call.

const DefaultPostamble = "Match their facial expression precisely to the emotion described. " +
	"Flat 2D illustration, no photographic realism, no text, letters, numbers or logos. " +
	"Subject in the upper two-thirds, empty space in the lower third. Vertical 9:16 portrait."

DefaultPostamble closes every panel prompt — the expression-lock plus the no-text / composition / aspect rules. The "only N people" constraint is added separately (count-aware) so multi-avatar panels aren't told "no other people". Style-independent; overridable per avatar.

Variables

var ErrNotFound = errors.NewSentinel("keyrx.not_found", "avatar not found")

ErrNotFound is returned when an avatar name is not in the registry.

Functions

func Compose

func Compose(cast []Named, scene, themeStyle string) string

Compose builds a panel prompt for one or more avatars: likeness(es) + style (themeStyle when restyling to a theme, else the first avatar's own Style) + the per-panel scene direction + the count-aware people constraint + the postamble. scene carries the actor direction (pose + prop + gaze + an explicit emotion — avatars default to a friendly expression). For multiple avatars the scene should direct each figure by name ("matt recoils while jane points").

Types

type Avatar

type Avatar struct {
	// Ref is the character reference image, project-relative.
	Ref string `json:"ref,omitempty" mapstructure:"ref"`
	// Likeness is the theme-independent description of the person.
	Likeness string `json:"likeness,omitempty" mapstructure:"likeness"`
	// Style is the avatar's OWN base art style, used when not restyling to a
	// theme.
	Style string `json:"style,omitempty" mapstructure:"style"`
	// Palette is the avatar's own palette (informational; folded into Style use).
	Palette string `json:"palette,omitempty" mapstructure:"palette"`
	// Postamble overrides DefaultPostamble when set.
	Postamble string `json:"postamble,omitempty" mapstructure:"postamble"`
}

Avatar is one registered character. Likeness/Style/Palette are typically captured by first-use analysis (spec 0006 §4) and are user-editable.

func Analyse

func Analyse(ctx context.Context, d Describer, image provider.RefImage) (Avatar, error)

Analyse runs first-use analysis: describe the reference image with the analysis prompt and parse the reply into an Avatar profile (likeness/style/palette). Shared by the CLI (`avatar add`) and the studio's analyse endpoint (spec 0034 D3).

func Resolve

func Resolve(r config.Reader, name string) (Avatar, error)

Resolve looks up an avatar by name from config (`avatars.<name>`).

func (Avatar) Prompt

func (a Avatar) Prompt(scene, themeStyle string) string

Prompt composes a single-avatar panel prompt (a convenience over Compose).

type Describer

type Describer interface {
	Describe(ctx context.Context, req provider.DescribeRequest) (string, error)
}

Describer is the vision subset first-use analysis needs — satisfied by a provider.ImageProvider. Injectable so the studio + CLI share the engine and tests fake it.

type Named

type Named struct {
	Name   string
	Avatar Avatar
}

Named pairs a registry name with its resolved avatar (the name labels the figure in a multi-avatar prompt so the scene can direct each by name).