classify

Documentation

Overview

Package classify assigns a theme to a cluster using a three-stage pipeline: an optional Ollama vision model (constrained to the configured theme set) decides first; if it is unavailable, errors, or abstains, a pure-Go altitude heuristic applies; otherwise a guaranteed fallback theme is used (FR-004/FR-005).

Index

• Constants
• type Classifier
• type Method
  • func Label(ctx context.Context, c photo.Cluster, opts Options) (string, Method)
• type OllamaClassifier
  • func NewOllama(baseURL, model string, sample int, themes []string) *OllamaClassifier
  • func (o *OllamaClassifier) Classify(ctx context.Context, c photo.Cluster) (string, error)
  • func (o *OllamaClassifier) Preflight(ctx context.Context) Status
• type Options
• type RawExtractor
• type Status

Constants

const SmallGroupMax = 3

SmallGroupMax is the largest group size still classified using all photos.

Types

type Classifier

type Classifier interface {
	Classify(ctx context.Context, c photo.Cluster) (string, error)
}

Classifier produces a theme slug for a cluster (implemented by Ollama or a fake in tests). It returns "" with a nil error when it cannot decide.

type Method

type Method string

Method records how a cluster's theme was decided (for logging, SC-005).

const (
	// MethodHeuristic — decided by metadata alone (altitude → mountain).
	MethodHeuristic Method = "heuristic"
	// MethodModelAll — the model classified a small group using all its photos (≤3).
	MethodModelAll Method = "model-all"
	// MethodModelSample — the model classified a large group from a sample (>3).
	MethodModelSample Method = "model-sample"
	// MethodFallback — no theme was determined; the fallback theme was used.
	MethodFallback Method = "fallback"
)

func Label

func Label(ctx context.Context, c photo.Cluster, opts Options) (string, Method)

Label returns a configured theme for the cluster and the Method used. The model (if configured and reachable) decides first so it sees the actual scene; only when it is unavailable, errors, or abstains does the altitude heuristic apply, and the fallback theme last.

type OllamaClassifier

type OllamaClassifier struct {
	BaseURL string
	Model   string
	Sample  int
	Themes  []string
	Timeout time.Duration
	HTTP    *http.Client
	Logger  *slog.Logger
	Raw     RawExtractor // optional; extracts previews for RAW photos
}

OllamaClassifier asks a local Ollama vision model to pick one theme from the configured set for a cluster. Every call is bounded by a context timeout and retried once on a transient error. Any failure is the caller's cue to fall back.

func NewOllama

func NewOllama(baseURL, model string, sample int, themes []string) *OllamaClassifier

NewOllama builds an OllamaClassifier with sane defaults for the given themes.

func (*OllamaClassifier) Classify

func (o *OllamaClassifier) Classify(ctx context.Context, c photo.Cluster) (string, error)

Classify returns one configured theme slug for the cluster, or an error on failure (transport, timeout, or an answer outside the configured set).

func (*OllamaClassifier) Preflight

func (o *OllamaClassifier) Preflight(ctx context.Context) Status

Preflight checks that Ollama is reachable and the configured model is installed, by querying GET {BaseURL}/api/tags. It is bounded by a short timeout and never blocks the run: any problem is reported as a Status the caller logs and acts on.

type Options

type Options struct {
	Themes     []string   // configured theme slugs
	Fallback   string     // theme used when none is determined
	Classifier Classifier // optional; nil skips the model stage
}

Options configures the labelling pipeline.

type RawExtractor

type RawExtractor interface {
	Extract(ctx context.Context, rawPath string) ([]byte, error)
}

RawExtractor turns a RAW file into model-viewable image bytes (its embedded JPEG preview). It is implemented by *rawpreview.Extractor. A nil RawExtractor disables RAW input: RAW photos are then skipped for the model (like HEIC).

type Status

type Status int

Status is the outcome of an Ollama Preflight check.

const (
	// StatusReady means Ollama answered and the configured model is installed.
	StatusReady Status = iota
	// StatusUnreachable means the Ollama endpoint could not be contacted.
	StatusUnreachable
	// StatusModelMissing means Ollama is reachable but the model is not pulled.
	StatusModelMissing
)