Documentation
¶
Overview ¶
Package scoring implements the importance scoring business logic for Cortex.
The scoring system tracks observation importance based on access patterns, recency, relationships, type, and age. Scores are used to prioritize observations in search results and recommendations.
Index ¶
- Constants
- func GetAllTypeBonuses() map[string]float64
- func GetTypeBonus(obsType string) float64
- type Repository
- type Service
- func (s *Service) CalculateScore(ctx context.Context, obsID int64) (float64, error)
- func (s *Service) DecayScores(ctx context.Context) error
- func (s *Service) GetScore(ctx context.Context, obsID int64) (*domain.ImportanceScore, error)
- func (s *Service) GetTop(ctx context.Context, project string, limit int) ([]*domain.ImportanceScore, error)
- func (s *Service) RecalculateAll(ctx context.Context) error
- func (s *Service) RecordAccess(ctx context.Context, obsID int64) error
- func (s *Service) SetNowFunc(fn func() time.Time)
Constants ¶
const ( // BaseScore is the starting score for all observations. BaseScore = 0.5 // AccessBonusPerAccess is added for each access (0.1 per access). AccessBonusPerAccess = 0.1 // MaxAccessBonus caps the total access bonus. MaxAccessBonus = 1.0 // RecencyBonus is added if accessed within the recency window. RecencyBonus = 0.5 // RecencyWindow is the time window for recency bonus (24 hours). RecencyWindow = 24 * time.Hour // EdgeBonusPerEdge is added for each incoming edge (0.2 per edge). EdgeBonusPerEdge = 0.2 // MaxEdgeBonus caps the total edge bonus. MaxEdgeBonus = 1.0 // AgePenaltyPerDay is subtracted per day since creation (0.01 per day). AgePenaltyPerDay = 0.01 // MaxAgePenalty caps the age penalty. MaxAgePenalty = 0.5 // DecayFactor is the multiplier applied during decay operations. DecayFactor = 0.95 // MinScore is the minimum allowed score (floor). MinScore = 0.0 // MaxScore is the maximum allowed score (ceiling). MaxScore = 5.0 )
Scoring constants defining the formula coefficients.
Variables ¶
This section is empty.
Functions ¶
func GetAllTypeBonuses ¶
GetAllTypeBonuses returns a copy of the type bonus map.
func GetTypeBonus ¶
GetTypeBonus returns the bonus for a given observation type. Returns 0 for unknown types.
Types ¶
type Repository ¶
type Repository interface {
domain.ScoringRepository
// GetScore retrieves the importance score for an observation.
// Returns ErrNotFound if the observation exists but has no score record.
GetScore(ctx context.Context, obsID int64) (*domain.ImportanceScore, error)
// RecordAccess increments the access count and updates last_accessed timestamp.
// Creates a new score record if one doesn't exist.
RecordAccess(ctx context.Context, obsID int64) error
// SetScore updates the score value for an observation.
SetScore(ctx context.Context, obsID int64, score float64) error
// GetAllScores retrieves all scores for batch operations like decay.
GetAllScores(ctx context.Context) ([]*domain.ImportanceScore, error)
// GetTopByScore retrieves the top-N highest scored observations for a project.
GetTopByScore(ctx context.Context, project string, limit int) ([]*domain.ImportanceScore, error)
// GetIncomingEdgeCount returns the number of edges pointing to this observation.
GetIncomingEdgeCount(ctx context.Context, obsID int64) (int, error)
// GetObservation retrieves observation data needed for score calculation.
GetObservation(ctx context.Context, obsID int64) (*domain.Observation, error)
}
Repository extends domain.ScoringRepository with additional methods needed for scoring operations. The store package implements this interface.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service implements the scoring business logic.
func NewService ¶
func NewService(repo Repository) *Service
NewService creates a new scoring service.
func (*Service) CalculateScore ¶
CalculateScore computes the importance score based on multiple factors:
Score = base + accessBonus + recencyBonus + edgeBonus + typeBonus - agePenalty
Where:
- base: BaseScore (0.5)
- accessBonus: +0.1 per access (max 1.0)
- recencyBonus: +0.5 if accessed in last 24 hours
- edgeBonus: +0.2 per incoming edge (max 1.0)
- typeBonus: +0.5 (decision), +0.3 (bugfix), +0.2 (pattern), etc.
- agePenalty: -0.01 per day since creation (max 0.5)
Score is clamped to [0.0, 5.0].
func (*Service) DecayScores ¶
DecayScores reduces all scores by the decay factor (0.95). This should be run periodically to naturally reduce importance of unused observations over time.
func (*Service) GetTop ¶
func (s *Service) GetTop(ctx context.Context, project string, limit int) ([]*domain.ImportanceScore, error)
GetTop retrieves the top-N most important observations for a project. Results are sorted by score in descending order.
func (*Service) RecalculateAll ¶
RecalculateAll forces recalculation of all scores. This is useful after bulk changes or migration.
func (*Service) RecordAccess ¶
RecordAccess increments access count and updates last_accessed timestamp. Score recalculation is deferred to the next explicit CalculateScore call to avoid 5 cascading DB queries per access.
func (*Service) SetNowFunc ¶
SetNowFunc allows injecting a custom time function for testing.
Source Files