gaps

Documentation

Overview

Package gaps finds concepts semantically near a seed page but not yet linked to it — the candidate cross-links / bridges a bundle author might add to refine a topic. Detection is deterministic; composing the bridge is the agent's job.

Index

• type Direct
• type Hole
• type Neighbor
• type Params
• type Result
  • func Find(b *bundle.Bundle, seed *bundle.Doc, p Params) (*Result, error)

Types

type Direct

type Direct struct {
	Page string  `json:"page"`
	Sim  float64 `json:"sim"`
}

Direct is a neighbor that is near the seed but not linked to it — a candidate direct cross-link.

type Hole

type Hole struct {
	A   string  `json:"a"`
	B   string  `json:"b"`
	Sim float64 `json:"sim"`
}

Hole is a pair among the seed's neighbors that are mutually near yet unlinked — an open triangle / local structural hole.

type Neighbor

type Neighbor struct {
	Page   string  `json:"page"`
	Sim    float64 `json:"sim"`
	Linked bool    `json:"linked"`
}

Neighbor is a concept near the seed and whether it is already cross-linked.

type Params

type Params struct {
	Depth   string          // "direct" | "neighborhood"
	Top     int             // neighbors to consider
	MinSim  float64         // similarity floor
	Exclude map[string]bool // node types to skip, lowercased
	Runner  qmd.Runner
}

Params configures a gaps search. Runner is the qmd invoker: leave it nil in production (qmd resolves the real binary from config) and inject a fake in tests — the dependency is accepted here, not created inside the algorithm.

type Result

type Result struct {
	Seed      string     `json:"seed"`
	Neighbors []Neighbor `json:"neighbors"`
	Direct    []Direct   `json:"direct"`
	Holes     []Hole     `json:"holes,omitempty"`
	SeedLinks []string   `json:"-"`
}

Result is the complete, self-describing output of a gaps search: everything a renderer needs without re-querying the bundle. SeedLinks lists the seed's existing links for human output only and stays off the JSON wire.

func Find

func Find(b *bundle.Bundle, seed *bundle.Doc, p Params) (*Result, error)

Find reports concepts semantically near the seed but not linked to it. With Depth == "neighborhood" it also finds unlinked pairs among those neighbors (open triangles), at the cost of one extra qmd query per neighbor.