graph

type BatchKnowledgeGraph interface {
	KnowledgeGraph
	// AddNodeBatch adds multiple nodes to the graph.
	AddNodeBatch(ctx context.Context, nodes []Node) error
	// UpsertNodeBatch inserts or updates multiple nodes.
	UpsertNodeBatch(ctx context.Context, nodes []Node) error
	// AddEdgeBatch adds multiple edges to the graph.
	AddEdgeBatch(ctx context.Context, edges []Edge) error
	// UpsertEdgeBatch inserts or updates multiple edges.
	UpsertEdgeBatch(ctx context.Context, edges []Edge) error
	// DeleteNodeBatch removes multiple nodes and their edges.
	DeleteNodeBatch(ctx context.Context, ids []string) error
}

type Edge struct {
	// From is the source node ID.
	From string
	// To is the target node ID.
	To string
	// Type is the edge type (e.g., "relates_to", "part_of", "caused_by").
	Type string
	// Weight is the edge weight (0.0-1.0).
	Weight float64
	// Metadata contains additional edge metadata.
	Metadata map[string]string
}

type GraphConfig struct {
	// Name is the graph name.
	Name string
	// NodeTypes defines the allowed node types (empty means any).
	NodeTypes []string
	// EdgeTypes defines the allowed edge types (empty means any).
	EdgeTypes []string
	// Directed indicates if the graph is directed.
	Directed bool
}

type GraphManager interface {
	// CreateGraph creates a new knowledge graph.
	CreateGraph(ctx context.Context, cfg GraphConfig) error
	// DropGraph removes a graph.
	DropGraph(ctx context.Context, name string) error
	// GraphExists checks if a graph exists.
	GraphExists(ctx context.Context, name string) (bool, error)
	// GraphStats returns statistics for a graph.
	GraphStats(ctx context.Context, name string) (*GraphStats, error)
	// ListGraphs returns all graph names.
	ListGraphs(ctx context.Context) ([]string, error)
}

type GraphStats struct {
	// Name is the graph name.
	Name string
	// NodeCount is the number of nodes.
	NodeCount int64
	// EdgeCount is the number of edges.
	EdgeCount int64
	// NodeTypeStats maps node types to counts.
	NodeTypeStats map[string]int64
	// EdgeTypeStats maps edge types to counts.
	EdgeTypeStats map[string]int64
}

type KnowledgeGraph interface {
	// Traverse performs a graph traversal starting from the given nodes.
	Traverse(ctx context.Context, startNodes []string, opts TraversalOptions) (*TraversalResult, error)
	// FindNodes finds nodes matching the given criteria.
	FindNodes(ctx context.Context, nodeType string, filters map[string]string) ([]Node, error)
	// AddNode adds a node to the graph.
	AddNode(ctx context.Context, node Node) error
	// UpsertNode inserts or updates a node in the graph.
	UpsertNode(ctx context.Context, node Node) error
	// AddEdge adds an edge to the graph.
	AddEdge(ctx context.Context, edge Edge) error
	// UpsertEdge inserts or updates an edge in the graph.
	UpsertEdge(ctx context.Context, edge Edge) error
	// DeleteNode removes a node and its edges from the graph.
	DeleteNode(ctx context.Context, id string) error
	// DeleteEdge removes an edge from the graph.
	DeleteEdge(ctx context.Context, from, to, edgeType string) error
	// Name returns the name/identifier of this graph.
	Name() string
}

type Node struct {
	// ID is the unique identifier for this node.
	ID string
	// Type is the node type (e.g., "concept", "document", "entity").
	Type string
	// Content is the text content of this node.
	Content string
	// Source identifies where this node came from.
	Source string
	// Metadata contains additional node metadata.
	Metadata map[string]string
}

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

type RetrieverConfig struct {
	// Graph is the knowledge graph to traverse.
	Graph KnowledgeGraph
	// DefaultDepth is the default traversal depth.
	DefaultDepth int
	// DefaultMaxNodes is the default maximum nodes to return.
	DefaultMaxNodes int
	// EdgeTypes filters which edge types to traverse by default.
	EdgeTypes []string
	// Observer for tracing and metrics.
	Observer retrieve.Observer
}

type TraversalOptions struct {
	// Depth is the maximum traversal depth.
	Depth int
	// EdgeTypes filters which edge types to traverse.
	EdgeTypes []string
	// NodeTypes filters which node types to include.
	NodeTypes []string
	// MaxNodes limits the total number of nodes to return.
	MaxNodes int
	// MinWeight is the minimum edge weight to traverse.
	MinWeight float64
}

type TraversalResult struct {
	// Nodes are the nodes found during traversal.
	Nodes []Node
	// Edges are the edges traversed.
	Edges []Edge
	// Paths maps node IDs to their traversal paths.
	Paths map[string][]string
}