queries

type Candidate ¶

type Candidate struct {
	NodeID   string
	TurnUUID string
	Text     string
}

Candidate is a single returned chunk handed to the Judge.

type Category ¶

type Category string

Category labels the kind of query for per-bucket metric reporting. Generators produce queries grouped by category and downstream metric aggregation slices results by category.

const (
	// CategoryParaphrase: lightly reworded version of a known turn —
	// the gold turn should rank top-1.
	CategoryParaphrase Category = "paraphrase"
	// CategoryNegation: query that should NOT match the named turn.
	CategoryNegation Category = "negation"
	// CategoryTopicJump: query targets a topic only one specific turn covered.
	CategoryTopicJump Category = "topic-jump"
	// CategoryDistractor: query similar in surface form but topically distinct.
	CategoryDistractor Category = "distractor"
	// CategoryStaleRelevant: query targets an old turn — tests decay vs relevance.
	CategoryStaleRelevant Category = "stale-relevant"
	// CategoryTemporal: query references a time window ("yesterday").
	CategoryTemporal Category = "temporal"
)

func AllCategories() []Category

type FakeGenerator ¶

type FakeGenerator struct{}

FakeGenerator emits deterministic per-turn queries for tests. It does NOT use any external service. Output:

• paraphrase: the first sentence of the turn, prefixed with "about:"
• distractor: a phrase guaranteed not to appear in the corpus

func NewFakeGenerator() *FakeGenerator

func (FakeGenerator) Generate(_ context.Context, turns []corpus.StoredTurn, req GenerateRequest) ([]LabeledQuery, error)

func (FakeGenerator) Version() string

type FakeJudge ¶

type FakeJudge struct{}

FakeJudge declares any candidate whose text shares a non-trivial token with the query "relevant" (score 1.0); everything else 0.0.

func NewFakeJudge() *FakeJudge

func (FakeJudge) Judge(_ context.Context, q LabeledQuery, cands []Candidate) ([]Verdict, error)

func (FakeJudge) Version() string

type GenerateRequest ¶

type GenerateRequest struct {
	Categories []Category
	TargetN    int // per category
}

GenerateRequest configures one Generator.Generate call.

type Generator ¶

type Generator interface {
	// Version is the generator-version field used as part of the
	// dedup key. Bump when the prompting strategy changes.
	Version() string
	// Generate returns up to req.TargetN queries per category in
	// req.Categories, drawn from `turns`.
	Generate(ctx context.Context, turns []corpus.StoredTurn, req GenerateRequest) ([]LabeledQuery, error)
}

Generator turns a corpus into a labeled query set. Implementations must be deterministic given the same (corpus, request) pair — the dedup key in the queries store assumes identical re-runs produce identical outputs.

type Judge ¶

type Judge interface {
	Version() string
	Judge(ctx context.Context, q LabeledQuery, candidates []Candidate) ([]Verdict, error)
}

Judge scores a (query, candidate) pair as relevant or not. Used to expand gold labels after a run by asking an LLM "did the candidate actually answer this query?" Returned scores are in [0, 1].

type LabeledQuery ¶

type LabeledQuery struct {
	ID            string
	Category      Category
	Text          string
	GoldTurnUUIDs []string
	Notes         string
	GeneratedAt   time.Time
}

LabeledQuery is the unit a Generator produces and a query battery consumes. GoldTurnUUIDs are the corpus turn UUIDs whose chunks should be considered "correct hits"; metrics map them to memmy node IDs at scoring time via the source turn UUID stored in node text.

type Store ¶

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

Store is the per-dataset queries.sqlite handle.

func OpenStore(path string) (*Store, error)

func (s *Store) All(ctx context.Context) ([]LabeledQuery, error)

func (s *Store) ByCategory(ctx context.Context, c Category) ([]LabeledQuery, error)

func (s *Store) Close() error

func (s *Store) Count(ctx context.Context) (int, error)

func (s *Store) CountForGeneration(ctx context.Context, generatorVersion, corpusSnapshotHash string, category Category) (int, error)

func (s *Store) Embedding(ctx context.Context, queryID string, dim int) ([]float32, bool, error)

func (s *Store) Put(ctx context.Context, q LabeledQuery, generatorVersion, corpusSnapshotHash string) error

func (s *Store) PutEmbedding(ctx context.Context, queryID string, vec []float32) error

type Verdict ¶

type Verdict struct {
	NodeID string
	Score  float64 // 0..1, higher = more relevant
	Reason string
}

Verdict is the Judge's assessment of one candidate.