interest

Documentation

Index

• func Persist(ctx context.Context, agentID string, st PersistStore, vi PersistVec, ...) error
• type Adjudication
  • func Adjudicate(ctx context.Context, agentID string, em Embedder, cl ClusterLLM, ...) (Adjudication, error)
• type ArchivedPoint
• type ClusterLLM
• type ClusterResult
  • func Cluster(ctx context.Context, agentID string, vi VectorIndex, st Store, pts []Point, ...) (ClusterResult, error)
• type Component
• type Embedder
• type FinalPoint
• type HistPoint
• type PersistStore
• type PersistVec
• type Point
  • func DedupeMerge(ctx context.Context, agentID string, em Embedder, cl ClusterLLM, ...) ([]Point, error)
• type Store
• type VectorIndex

Functions

func Persist

func Persist(ctx context.Context, agentID string, st PersistStore, vi PersistVec, adj Adjudication, relateSim float64) error

Persist writes an Adjudication (V1.2 output) to the store:

• final points (create/update) are upserted with their embeddings + logs
• archived historical points are marked archived, their vectors deleted
• contradictions are stored with bidirectional contradicts edges
• programmatic related edges are generated among all surviving points whose pairwise embedding cosine ≥ relateSim, weight = cosine.

This is the V1.3 stage: the whole batch must be adjudicated (V1.2) before anything is persisted here.

Types

type Adjudication

type Adjudication struct {
	FinalPoints    []FinalPoint
	Archived       []ArchivedPoint
	Contradictions []store.Contradiction
}

Adjudication is V1.2's output: the points with real changes (create/update) plus archived historical points and contradiction pairs. It never persists.

func Adjudicate

func Adjudicate(ctx context.Context, agentID string, em Embedder, cl ClusterLLM, res ClusterResult, maxConc int) (Adjudication, error)

Adjudicate is pipeline stage V1.2: per-component and per-isolated-point LLM adjudication over the s2 ClusterResult. Inputs are a snapshot (no cascade); output carries final points (with embeddings) and contradictions for V1.3. A component whose decisions omit any member is voided wholesale: its historical points are untouched, all its members become new points, and its contradictions are dropped. Never persists.

type ArchivedPoint

type ArchivedPoint struct {
	Pt store.InterestPoint
}

ArchivedPoint is a historical point the adjudication decided to archive.

type ClusterLLM

type ClusterLLM interface {
	ChatJSON(ctx context.Context, messages []llm.Message, out any) error
}

ClusterLLM is the chat surface s1's per-cluster merge judgment needs (implemented by *llm.Client). Narrow for test fakes.

type ClusterResult

type ClusterResult struct {
	Components []Component
	Isolated   []Point
	Conflicts  [][]Component
}

ClusterResult is s2's output: connected components, isolated current points (no similar partner), and conflict queues — components that share a historical point and must be adjudicated in order (highest shared-point affinity first). Conflict components are removed from Components and appear only in their queue.

func Cluster

func Cluster(ctx context.Context, agentID string, vi VectorIndex, st Store, pts []Point, mergeSim, histSim float64) (ClusterResult, error)

Cluster is pipeline stage s2: build pairwise similarity pairs among current points (> mergeSim) and between each current point and historical interest points (> histSim, via vec.Search + vec.Get for the exact vector), then group into connected components.

A conflict arises when a historical point H is shared by two or more components (each component's current-point leader is similar to H): the components compete for H, so they are pulled out of the flat component list into a conflict queue, ordered by H's affinity to each component's leader (highest first — adjudicated first). Everything else forms plain components; current points with no similar partner at all are Isolated. Never persists and never calls the LLM.

type Component

type Component struct {
	Members    []Point
	Hist       []HistPoint
	MemberHist map[string][]HistPoint
}

Component is one connected component of similar points (the unit of V1.2's per-group LLM adjudication). Members are current points (cluster leaders); Hist are historical points similar to ≥1 member. MemberHist preserves the per-member association (member topic → the historical points it is similar to) so V1.2 can adjudicate each current↔historical pair explicitly.

type Embedder

type Embedder interface {
	Embed(ctx context.Context, text string) ([]float32, error)
}

Embedder computes embeddings for candidate text (implemented by *llm.Embedder, which carries the T2 content-hash LRU cache).

type FinalPoint

type FinalPoint struct {
	Point  store.InterestPoint
	Vec    []float32
	Action string // create | update | archive
}

FinalPoint is one interest point that a V1.2 adjudication decided to create/update/archive, ready for V1.3 to persist (with its embedding).

type HistPoint

type HistPoint struct {
	Pt  store.InterestPoint
	Vec []float32
}

HistPoint is a historical interest point joined into a component because it is similar to a current-point leader. Pt carries the full record; Vec the stored embedding fetched via VectorIndex.Get.

type PersistStore

type PersistStore interface {
	UpsertInterestPoint(ctx context.Context, p store.InterestPoint) error
	AddEdgePairs(ctx context.Context, agentID string, edges []store.Edge) error
	AppendLog(ctx context.Context, l store.ChangeLog) error
	UpsertContradiction(ctx context.Context, c store.Contradiction) error
}

PersistStore is the persistence surface V1.3 needs (implemented by *store.SQLiteStore). Kept narrow for test fakes.

type PersistVec

type PersistVec interface {
	Upsert(ctx context.Context, e vec.Entry) error
	Delete(ctx context.Context, agentID, id string) error
}

PersistVec is the vector surface V1.3 needs (implemented by vec.VectorIndex).

type Point

type Point struct {
	Candidate fork.Candidate
	Vec       []float32
}

Point is a deduped/merged interest point produced by DedupeMerge (s1) and consumed by Cluster (s2). Vec is the candidate's embedding, computed once and reused so s2 never re-embeds the same text.

func DedupeMerge

func DedupeMerge(ctx context.Context, agentID string, em Embedder, cl ClusterLLM, clusterSim float64, maxConc int, cands []fork.Candidate) ([]Point, error)

DedupeMerge is pipeline stage s1: fold identical topics (string-normalized) for free, cluster remaining candidates by embedding similarity (> clusterSim pairs), and ask the LLM once per cluster how to merge/keep its members. Returns the merged interest points with their embeddings. Never persists. Embedding and per-cluster LLM calls run in parallel (maxConc workers, fail-fast on the first error), while the output order matches the serial pipeline (input order / cluster order).

type Store

type Store interface {
	GetInterestPoint(ctx context.Context, agentID, id string) (*store.InterestPoint, error)
	UpsertInterestPoint(ctx context.Context, p store.InterestPoint) error
	AddEdgePair(ctx context.Context, agentID string, e store.Edge) error
	AppendLog(ctx context.Context, l store.ChangeLog) error
}

Store is the persistence surface s2 clustering needs (implemented by *store.SQLiteStore).

type VectorIndex

type VectorIndex interface {
	Search(ctx context.Context, agentID string, q []float32, topK int) ([]vec.Hit, error)
	// Get fetches the stored entry (including its raw embedding vector) for a
	// historical id, so s2 can recompute exact pairwise similarity instead of
	// trusting Search's ranking score.
	Get(ctx context.Context, agentID, id string) (*vec.Entry, error)
	Upsert(ctx context.Context, e vec.Entry) error
	Delete(ctx context.Context, agentID, id string) error
}

VectorIndex is the recall surface for historical interest points (implemented by vec.SQLiteVec / vec.Fallback).