Documentation
¶
Overview ¶
Package merkle is an implementation of a Merkel DAG
Index ¶
- type Bucket
- type Dag
- func (d *Dag) AddNode(node *Node) (*DagNode, error)
- func (d *Dag) Ancestors(hash string) []*DagNode
- func (d *Dag) BranchPoints() []*DagNode
- func (d *Dag) Descendants(hash string) []*DagNode
- func (d *Dag) Get(hash string) *DagNode
- func (d *Dag) IsBranching(hash string) bool
- func (d *Dag) Leaves() []*DagNode
- func (d *Dag) Size() int
- func (d *Dag) Walk(f func(*DagNode) (bool, error)) error
- type DagNode
- type Node
- type NodeOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bucket ¶
type Bucket struct {
// Type identifies the kind of content (e.g., "message")
Type string `json:"type"`
// Role indicates who produced this message ("system", "user", "assistant", "tool")
Role string `json:"role"`
// Content holds the message content blocks
Content []llm.ContentBlock `json:"content"`
// Model identifies the LLM model (e.g., "gpt-4", "claude-3-sonnet")
Model string `json:"model"`
// Provider identifies the API provider (e.g., "openai", "anthropic", "ollama")
Provider string `json:"provider"`
// AgentName identifies the agent harness (e.g., "claude", "opencode", "codex")
AgentName string `json:"agent_name,omitempty"`
}
Bucket represents the hashable content stored in a Merkle DAG node. This is the tapes canonical content-addressable hashing structure for all LLM conversation turns.
func (*Bucket) ExtractText ¶
ExtractText returns the concatenated text content from the bucket's content blocks. This is useful for generating embeddings for semantic search. It extracts text from text blocks, tool outputs, and tool use requests, joining them with newlines.
type Dag ¶
type Dag struct {
// Root is the single root node of this directed graph
Root *DagNode
// contains filtered or unexported fields
}
Dag is an in-memory view of a single-rooted Merkle DAG (i.e., a single branch within the graph's plane).
It is loaded on-demand from a provided BranchLoader.
func (*Dag) AddNode ¶ added in v0.5.0
AddNode adds a node to the given DAG. The node's ParentHash must reference an existing node in the DAG, or be nil (making it the root).
This method returns an error if:
- The provided node is nil: this is a programmer error.
- The parent hash references a node not in the DAG (this node does not belong in this branch)
- Adding a root node (where node.Parent is empty) when one already exists
This method is a noop if:
- The node already exists in the DAG
func (*Dag) Ancestors ¶
Ancestors returns the path from the given node up to the root. The returned slice is ordered from the node to root (node first, root last). Returns nil if the hash is not found.
func (*Dag) BranchPoints ¶
BranchPoints returns all nodes that have more than one child.
func (*Dag) Descendants ¶
Descendants returns all descendants of the given node (children, grandchildren, etc.). The returned slice is ordered by depth-first traversal. Returns nil if the hash is not found.
func (*Dag) IsBranching ¶
IsBranching returns true if the node with the given hash has multiple children. Returns false if the hash is not found or has 0-1 children.
type DagNode ¶
type DagNode struct {
*Node
// Parent is the parent node in the DAG (nil for root)
Parent *DagNode
// Children are the child nodes (empty for leaves)
Children []*DagNode
}
DagNode wraps a "Node" with structural relationships for efficient traversal.
type Node ¶
type Node struct {
// Hash is the content-addressed identifier (SHA-256, hex-encoded)
Hash string `json:"hash"`
// ParentHash links to the previous node hash.
// This will be nil for root nodes.
ParentHash *string `json:"parent_hash"`
// Bucket is the hashable content for the node.
Bucket Bucket `json:"bucket"`
// StopReason indicates why generation stopped (only for responses)
// Values: "stop", "length", "tool_use", "end_turn", etc.
StopReason string `json:"stop_reason,omitempty"`
// Usage contains token counts and timing (only for responses)
Usage *llm.Usage `json:"usage,omitempty"`
// Project is the git repository or project name that produced this node
Project string `json:"project,omitempty"`
// CreatedAt is the time the node was persisted to storage. It is populated
// by the storage layer (not by NewNode) and is NOT part of the content hash.
// Zero value means "unknown" — typically for nodes constructed in-memory
// that have not yet been Put.
CreatedAt time.Time `json:"created_at,omitzero"`
}
Node represents a single content-addressed node in a Merkle DAG
Source Files