knn

Documentation

Overview

Package knn implements a zero-training k-nearest-neighbor entry-tier pre-filter over embeddinggemma vectors of past inputs. It is a bridge before the LR router (internal/router) has enough rows to train: it predicts whether the small E2B tier will accept an input, from the E2B-accept labels the shadow-labeling flywheel already manufactures, embedded at drain time. Brute-force cosine; fail-open; nil-safe.

Index

• func Append(path string, r Row) error
• type Index
  • func Load(path string) *Index
  • func (ix *Index) PreferLargerEntry(task string, query []float64, k, minNeighbors int, threshold float64) (skip bool, ok bool)
• type Row

Functions

func Append

func Append(path string, r Row) error

Append writes one row as a JSON line (O_APPEND, concurrency-safe). It creates the parent directory if needed.

Types

type Index

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

Index holds per-task labeled vectors loaded from a JSONL substrate. A nil *Index is safe to query (PreferLargerEntry returns no preference).

func Load

func Load(path string) *Index

Load reads the JSONL substrate at path. Returns nil if the file is absent or unreadable (caller treats nil as "no kNN preference"); malformed lines are skipped. A present-but-empty file yields a non-nil, empty Index.

func (*Index) PreferLargerEntry

func (ix *Index) PreferLargerEntry(task string, query []float64, k, minNeighbors int, threshold float64) (skip bool, ok bool)

PreferLargerEntry returns (skip, ok). skip=true means the kNN predicts E2B will NOT accept this input — the fraction of the k nearest same-task neighbors that accepted at E2B is below threshold — so the caller should skip E2B and enter at a larger tier. ok=false signals no usable signal (nil receiver, unknown task, empty query, or fewer than minNeighbors usable rows): the caller keeps the default entry. Rows whose vector dimension differs from the query are ignored.

type Row

type Row struct {
	Task   string    `json:"task"`
	Vec    []float64 `json:"vec"`
	Accept bool      `json:"accept"`
}

Row is one labeled substrate point: the embedding of a past input and whether the small E2B tier accepted it.