types.go raw

   1  package grapevine
   2  
   3  import "time"
   4  
   5  // ScoreEntry holds computed influence and WoT scores for a single target pubkey.
   6  type ScoreEntry struct {
   7  	PubkeyHex string  `json:"pubkey"`
   8  	Influence float64 `json:"influence"`
   9  	Average   float64 `json:"average"`
  10  	Certainty float64 `json:"certainty"`
  11  	Input     float64 `json:"input"`
  12  	WoTScore  int     `json:"wot_score"` // intersection count: how many of observer's follows also follow this target
  13  	Depth     int     `json:"depth"`     // BFS hop distance from observer
  14  }
  15  
  16  // ScoreSet is the complete result for one observer.
  17  type ScoreSet struct {
  18  	ObserverHex  string       `json:"observer"`
  19  	Scores       []ScoreEntry `json:"scores"`
  20  	ComputedAt   time.Time    `json:"computed_at"`
  21  	ComputeMs    int64        `json:"compute_ms"`
  22  	TotalPubkeys int          `json:"total_pubkeys"`
  23  }
  24  
  25  // Config holds algorithm tuning parameters.
  26  type Config struct {
  27  	MaxDepth          int     // BFS hop depth (default 6)
  28  	Cycles            int     // convergence iterations (default 5)
  29  	AttenuationFactor float64 // weight decay for non-observer raters (default 0.8)
  30  	Rigor             float64 // certainty curve steepness (default 0.25)
  31  	FollowConfidence  float64 // base confidence for a follow edge (default 0.05)
  32  }
  33  
  34  // DefaultConfig returns sensible defaults matching cloudfodder's original algorithm.
  35  func DefaultConfig() Config {
  36  	return Config{
  37  		MaxDepth:          6,
  38  		Cycles:            5,
  39  		AttenuationFactor: 0.8,
  40  		Rigor:             0.25,
  41  		FollowConfidence:  0.05,
  42  	}
  43  }
  44  
  45  // GraphSource provides read access to the follow graph.
  46  type GraphSource interface {
  47  	// TraverseFollowsOutbound does BFS outward from seed pubkey, returning
  48  	// pubkeys grouped by depth and a flat map of all pubkeys to their depth.
  49  	TraverseFollowsOutbound(seedPubkey []byte, maxDepth int) (
  50  		pubkeysByDepth map[int][]string, allPubkeys map[string]int, err error,
  51  	)
  52  	// GetFollowerPubkeys returns hex pubkeys of accounts that follow the target.
  53  	GetFollowerPubkeys(targetHex string) ([]string, error)
  54  	// GetFollowsPubkeys returns hex pubkeys that the source follows.
  55  	GetFollowsPubkeys(sourceHex string) ([]string, error)
  56  }
  57  
  58  // ScoreStore persists computed score sets as raw JSON blobs.
  59  // This avoids circular dependencies between the database and grapevine packages.
  60  type ScoreStore interface {
  61  	SaveScoreSet(observerHex string, setData []byte, entries map[string][]byte) error
  62  	GetScoreSet(observerHex string) ([]byte, error)
  63  	GetScore(observerHex, targetHex string) ([]byte, error)
  64  }
  65