retrieval

type ContextSearchAgent ¶

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

ContextSearchAgent performs semantic/vector search via RAGService and converts results to Findings. It covers the same factual layers as FactSearchAgent (UserKnowledge, AgentLearnings) but uses vector similarity instead of keyword matching. Results naturally rank below FTS5 scores (0-1 vs 1-10+), making this agent a "related context expansion" source, not authoritative truth.

v1 scope: knowledge + learning collections only; observation/reflection deferred to avoid budget boundary violation with memory section.

func NewContextSearchAgent(source ContextSearchSource, opts embedding.RetrieveOptions, logger *zap.SugaredLogger) *ContextSearchAgent

func (a *ContextSearchAgent) Layers() []knowledge.ContextLayer

func (a *ContextSearchAgent) Name() string

func (a *ContextSearchAgent) Search(ctx context.Context, query string, limit int) ([]Finding, error)

type ContextSearchSource ¶

type ContextSearchSource interface {
	Retrieve(ctx context.Context, query string, opts embedding.RetrieveOptions) ([]embedding.RAGResult, error)
}

ContextSearchSource provides vector/semantic search results. Satisfied by *embedding.RAGService.

type FactSearchAgent ¶

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

FactSearchAgent searches knowledge, learnings, and external references.

func NewFactSearchAgent(source FactSearchSource) *FactSearchAgent

func (a *FactSearchAgent) Layers() []knowledge.ContextLayer

func (a *FactSearchAgent) Name() string

func (a *FactSearchAgent) Search(ctx context.Context, query string, limit int) ([]Finding, error)

type FactSearchSource ¶

type FactSearchSource interface {
	SearchKnowledgeScored(ctx context.Context, query, category string, limit int) ([]knowledge.ScoredKnowledgeEntry, error)
	SearchLearningsScored(ctx context.Context, errorPattern, category string, limit int) ([]knowledge.ScoredLearningEntry, error)
	SearchExternalRefs(ctx context.Context, query string) ([]knowledge.ExternalRefEntry, error)
}

FactSearchSource is the narrow interface for fact-based search operations. Satisfied by *knowledge.Store.

type FeedbackProcessor ¶

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

FeedbackProcessor subscribes to ContextInjectedEvent and logs structured observability data about which context items were injected into each turn.

This processor is read-only — it does not modify relevance scores or stored data. Score auto-adjustment is handled by RelevanceAdjuster (separate subscriber).

func NewFeedbackProcessor(logger *zap.SugaredLogger) *FeedbackProcessor

func (p *FeedbackProcessor) Subscribe(bus *eventbus.Bus)

type Finding ¶

type Finding struct {
	Key      string  // unique identifier
	Content  string  // the retrieved text
	Score    float64 // normalized: higher = better
	Category string  // knowledge category

	// SearchSource is the retrieval METHOD used to find this item.
	// Values: "fts5", "like", "vector", "temporal".
	// NOT to be confused with Source (authorship origin below).
	SearchSource string

	Agent string                 // producing agent name
	Layer knowledge.ContextLayer // target context layer

	// Source is the AUTHORSHIP origin that produced this knowledge.
	// Values: "knowledge", "proactive_librarian", "session_learning",
	// "conversation_analysis", "memory", "learning".
	Source    string
	Tags      []string  // includes "temporal:evergreen", "temporal:current_state"
	Version   int       // version chain position (higher supersedes lower)
	UpdatedAt time.Time // last update timestamp
}

Finding represents a single retrieved item with provenance metadata.

func TruncateFindings(findings []Finding, tokenBudget int) []Finding

type RelevanceAdjuster ¶

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

RelevanceAdjuster subscribes to ContextInjectedEvent and optionally mutates relevance_score on knowledge entries. Items injected into context get boosted; all items decay periodically to prevent score inflation.

v1 signal scope: only old knowledge path items (ContextInjectedEvent.Items). Effect scope: primarily LIKE fallback search + coordinator merge priority.

func NewRelevanceAdjuster(store RelevanceStore, cfg RelevanceAdjusterConfig, logger *zap.SugaredLogger) *RelevanceAdjuster

func (a *RelevanceAdjuster) Mode() string

func (a *RelevanceAdjuster) SetMode(mode string)

func (a *RelevanceAdjuster) Subscribe(bus *eventbus.Bus)

type RelevanceAdjusterConfig ¶

type RelevanceAdjusterConfig struct {
	Mode          string // "shadow" or "active"
	BoostDelta    float64
	DecayDelta    float64
	DecayInterval int
	MinScore      float64
	MaxScore      float64
	WarmupTurns   int
}

RelevanceAdjusterConfig mirrors config.AutoAdjustConfig to avoid import cycle.

type RelevanceStore ¶

type RelevanceStore interface {
	BoostRelevanceScore(ctx context.Context, key string, delta, maxScore float64) error
	DecayAllRelevanceScores(ctx context.Context, delta, minScore float64) (int, error)
	ResetAllRelevanceScores(ctx context.Context) (int, error)
}

RelevanceStore defines the narrow interface for relevance score mutations. Satisfied by *knowledge.Store.

type RetrievalAgent ¶

type RetrievalAgent interface {
	Name() string
	Layers() []knowledge.ContextLayer
	Search(ctx context.Context, query string, limit int) ([]Finding, error)
}

RetrievalAgent retrieves findings for specific context layers.

type RetrievalCoordinator ¶

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

RetrievalCoordinator runs multiple RetrievalAgents in parallel and merges results.

func NewRetrievalCoordinator(agents []RetrievalAgent, logger *zap.SugaredLogger) *RetrievalCoordinator

func (c *RetrievalCoordinator) Retrieve(ctx context.Context, query string, tokenBudget int) ([]Finding, error)

type TemporalSearchAgent ¶

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

TemporalSearchAgent retrieves recently-updated knowledge entries and scores them by recency. It complements FactSearchAgent (keyword) and ContextSearchAgent (vector) by surfacing items based on freshness rather than textual relevance.

v1 scope: LayerUserKnowledge only. Learnings lack version chains and are excluded.

func NewTemporalSearchAgent(source TemporalSearchSource) *TemporalSearchAgent

func (a *TemporalSearchAgent) Layers() []knowledge.ContextLayer

func (a *TemporalSearchAgent) Name() string

func (a *TemporalSearchAgent) Search(ctx context.Context, query string, limit int) ([]Finding, error)

type TemporalSearchSource ¶

type TemporalSearchSource interface {
	SearchRecentKnowledge(ctx context.Context, query string, limit int) ([]knowledge.KnowledgeEntry, error)
}

TemporalSearchSource is the narrow interface for recency-based search. Satisfied by *knowledge.Store.