graph

Documentation

Index

• func SummarizeSubgraph(nodes []domain.SubgraphNode, edges []domain.SubgraphEdge) string
• type Edge
• type Graph
  • func New() *Graph
  • func (g *Graph) AddEdge(sourceID, targetID, relID, relType string, weight float64, validAt time.Time, ...)
  • func (g *Graph) EdgeCount() int
  • func (g *Graph) EntityCount() int
  • func (g *Graph) HasEntity(entityID string) bool
  • func (g *Graph) Neighbors(seeds []string, maxHops int) map[string]int
  • func (g *Graph) NeighborsAt(seeds []string, maxHops int, at time.Time) map[string]int
  • func (g *Graph) NeighborsFiltered(seeds []string, maxHops int, allowTypes []string) map[string]int
  • func (g *Graph) PersonalizedPageRank(seeds []string, alpha float64, maxIter int, epsilon float64) map[string]float64
  • func (g *Graph) RemoveEdge(relID string)
  • func (g *Graph) Subgraph(seeds []string, maxHops int, allowTypes []string) SubgraphResult
  • func (g *Graph) WeightedNeighbors(seeds []string, maxHops int, minWeight float64) map[string]float64
• type RelationLoader
• type Store
  • func NewStore() *Store
  • func (s *Store) Drop(kbID string)
  • func (s *Store) Get(kbID string) *Graph
  • func (s *Store) Has(kbID string) bool
  • func (s *Store) Load(ctx context.Context, kbID string, loader RelationLoader) error
• type SubgraphEdge
• type SubgraphResult

Functions

func SummarizeSubgraph

func SummarizeSubgraph(nodes []domain.SubgraphNode, edges []domain.SubgraphEdge) string

SummarizeSubgraph converts a subgraph into a compact natural language representation suitable for LLM context injection. Nodes are grouped by hop distance and their outgoing edges listed underneath.

Types

type Edge

type Edge struct {
	TargetID  string
	RelID     string     // relation ID for metadata lookup
	Type      string     // relation type ("works_on", "knows", etc.)
	Weight    float64    // confidence weight from extraction
	ValidAt   time.Time  // when the fact became true in the real world
	InvalidAt *time.Time // when it stopped being true (nil = still valid)
}

Edge represents a directed edge in the knowledge graph.

type Graph

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

Graph is a per-KB in-memory directed graph using adjacency lists. Supports BFS neighborhood expansion for hybrid search.

func New

func New() *Graph

New creates an empty graph.

func (*Graph) AddEdge

func (g *Graph) AddEdge(sourceID, targetID, relID, relType string, weight float64, validAt time.Time, invalidAt *time.Time)

AddEdge adds a directed edge from sourceID to targetID. Thread-safe.

func (*Graph) EdgeCount

func (g *Graph) EdgeCount() int

EdgeCount returns the number of edges in the graph.

func (*Graph) EntityCount

func (g *Graph) EntityCount() int

EntityCount returns the number of unique entities (nodes with at least one edge).

func (*Graph) HasEntity

func (g *Graph) HasEntity(entityID string) bool

HasEntity returns whether the entity has any edges.

func (*Graph) Neighbors

func (g *Graph) Neighbors(seeds []string, maxHops int) map[string]int

Neighbors returns all entity IDs reachable within maxHops from the seeds, traversing edges in both directions. Returns entityID -> minimum hop distance. Seeds themselves are included at distance 0.

func (*Graph) NeighborsAt

func (g *Graph) NeighborsAt(seeds []string, maxHops int, at time.Time) map[string]int

NeighborsAt returns entity IDs reachable within maxHops, only traversing edges that were valid at the given point in time.

func (*Graph) NeighborsFiltered

func (g *Graph) NeighborsFiltered(seeds []string, maxHops int, allowTypes []string) map[string]int

NeighborsFiltered returns entity IDs reachable within maxHops, restricted to the given edge types. If allowTypes is nil or empty, all edge types are traversed.

func (*Graph) PersonalizedPageRank

func (g *Graph) PersonalizedPageRank(seeds []string, alpha float64, maxIter int, epsilon float64) map[string]float64

PersonalizedPageRank computes PPR scores seeded from the given entity IDs. alpha is the teleport probability (typically 0.15), maxIter limits iterations, and epsilon is the convergence threshold.

func (*Graph) RemoveEdge

func (g *Graph) RemoveEdge(relID string)

RemoveEdge removes an edge by relation ID.

func (*Graph) Subgraph

func (g *Graph) Subgraph(seeds []string, maxHops int, allowTypes []string) SubgraphResult

Subgraph returns the N-hop ego-graph around seeds with full edge data. If allowTypes is non-empty, only edges with matching Type are traversed.

func (*Graph) WeightedNeighbors

func (g *Graph) WeightedNeighbors(seeds []string, maxHops int, minWeight float64) map[string]float64

WeightedNeighbors explores paths up to maxHops, tracking cumulative path weight as the product of edge weights. Only edges with Weight >= minWeight are traversed. Returns entityID -> best cumulative weight along any path from a seed.

The traversal keeps only the best weight per node at each exact hop depth. This bounds work by maxHops while preserving hop-limited semantics: a slightly worse path that reaches a node earlier can still be the only way to reach a better descendant within the remaining hop budget.

type RelationLoader

type RelationLoader interface {
	GetValidRelations(ctx context.Context, kbID string, at time.Time) ([]*domain.Relation, error)
}

RelationLoader loads valid relations for graph construction.

type Store

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

Store manages per-KB graph instances.

func NewStore

func NewStore() *Store

NewStore creates a graph store.

func (*Store) Drop

func (s *Store) Drop(kbID string)

Drop removes a KB's graph from the store.

func (*Store) Get

func (s *Store) Get(kbID string) *Graph

Get returns the graph for a KB, or nil if not loaded.

func (*Store) Has

func (s *Store) Has(kbID string) bool

Has returns whether a graph is loaded for the given KB.

func (*Store) Load

func (s *Store) Load(ctx context.Context, kbID string, loader RelationLoader) error

Load builds the graph for a KB from its current valid relations.

type SubgraphEdge

type SubgraphEdge struct {
	SourceID string
	TargetID string
	RelID    string
	Type     string
	Weight   float64
}

SubgraphEdge represents a collected edge within a subgraph result.

type SubgraphResult

type SubgraphResult struct {
	Nodes map[string]int // entityID -> hop distance from seed
	Edges []SubgraphEdge // edges connecting nodes within the subgraph
}

SubgraphResult holds the BFS neighborhood with both nodes and edges.