Documentation
¶
Overview ¶
Package leyline provides Go bindings to the ley-line C FFI.
The actual implementation requires the "leyline" build tag and a locally built libleyline_fs.a. See client.go for details.
Package leyline — semantic.go provides typed methods for the ley-line daemon's semantic search operations (embedding-based KNN search).
SemanticClient wraps a SocketClient and translates between mache's search requests and the daemon's semantic_search / embed_status / embed_content ops. All methods are no-ops when the underlying SocketClient is nil, making the integration fully optional.
Package leyline — sheaf.go provides typed methods for the ley-line daemon's sheaf (topology-aware cache invalidation) operations.
SheafClient wraps a SocketClient and translates between mache's community detection output and the daemon's sheaf_* UDS ops. All methods are no-ops when the underlying SocketClient is nil, making the integration fully optional.
Package leyline — trigger.go pushes graph content to the ley-line daemon for embedding. Called as a fire-and-forget goroutine after graph construction.
Index ¶
- func DiscoverOrStart() (string, error)
- func DiscoverSocket() (string, error)
- func StopManaged()
- func TriggerEmbedding(g graph.Graph, batchSize int)
- type EmbedStatus
- type NodeContent
- type SemanticClient
- type SemanticResult
- type SheafClient
- type SheafStatus
- type SocketClient
- func (c *SocketClient) Close() error
- func (c *SocketClient) Query(sql string) ([][]any, error)
- func (c *SocketClient) SendOp(req map[string]any) (map[string]any, error)
- func (c *SocketClient) SetDeadline(t time.Time) error
- func (c *SocketClient) Tool(name string, args map[string]any) (map[string]any, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DiscoverOrStart ¶
DiscoverOrStart finds a running ley-line daemon socket, or auto-starts a managed daemon subprocess if the leyline binary is on PATH.
The managed daemon uses ~/.mache/ as its data directory:
~/.mache/default.arena — arena file ~/.mache/default.ctrl — control block ~/.mache/default.sock — UDS socket (what we connect to) ~/.mache/mount/ — FUSE/NFS mount point
The subprocess is killed when the mache process exits (via atexit cleanup registered on first spawn). Only one managed daemon per process.
func DiscoverSocket ¶
DiscoverSocket finds the ley-line socket path by checking:
- LEYLINE_SOCKET environment variable
- ~/.mache/default.sock (well-known kiln deployment path)
Returns the path and nil error if a socket file exists, or an error if no socket can be found. Does NOT auto-start a daemon.
func StopManaged ¶
func StopManaged()
StopManaged gracefully stops the auto-spawned leyline daemon, if any. Sends SIGTERM first so leyline can unmount NFS cleanly, then waits up to 3 seconds before falling back to SIGKILL. Without this, macOS shows a "Server connections interrupted" dialog for the stale NFS mount. Safe to call multiple times. Called automatically by cleanup hooks.
func TriggerEmbedding ¶ added in v0.6.1
TriggerEmbedding walks all file nodes in the graph and pushes their content to the ley-line daemon for embedding via the embed_content op. Batches nodes in groups of batchSize. Logs errors but does not fail.
Types ¶
type EmbedStatus ¶ added in v0.6.1
type EmbedStatus struct {
Ready bool `json:"ready"`
Count int `json:"count"`
Dimensions int `json:"dimensions"`
Model string `json:"model"`
}
EmbedStatus reports the state of the embedding index.
type NodeContent ¶ added in v0.6.1
NodeContent is a node to embed: id + text content.
type SemanticClient ¶ added in v0.6.1
type SemanticClient struct {
// contains filtered or unexported fields
}
SemanticClient provides typed access to ley-line's embedding operations. A nil SemanticClient is safe — all methods return zero values without error.
func NewSemanticClient ¶ added in v0.6.1
func NewSemanticClient(sock *SocketClient) *SemanticClient
NewSemanticClient wraps an existing SocketClient. sock may be nil.
func (*SemanticClient) EmbedContent ¶ added in v0.6.1
func (sc *SemanticClient) EmbedContent(nodes []NodeContent) (int, error)
EmbedContent pushes node content to the daemon for embedding. Returns the number of nodes successfully embedded.
func (*SemanticClient) Search ¶ added in v0.6.1
func (sc *SemanticClient) Search(query string, k int) ([]SemanticResult, error)
Search performs a semantic search over embedded nodes. Returns results sorted by distance (closest first).
func (*SemanticClient) Status ¶ added in v0.6.1
func (sc *SemanticClient) Status() (EmbedStatus, error)
Status returns the current embedding index status.
type SemanticResult ¶ added in v0.6.1
SemanticResult is a single KNN search result.
type SheafClient ¶ added in v0.6.1
type SheafClient struct {
// contains filtered or unexported fields
}
SheafClient provides typed access to ley-line's sheaf operations. A nil SheafClient is safe — all methods return zero values without error.
func NewSheafClient ¶ added in v0.6.1
func NewSheafClient(sock *SocketClient) *SheafClient
NewSheafClient wraps an existing SocketClient. sock may be nil.
func (*SheafClient) Defect ¶ added in v0.6.1
func (sc *SheafClient) Defect() (float64, error)
Defect queries the global consistency defect score. Returns 0.0 when the daemon is unavailable.
func (*SheafClient) Invalidate ¶ added in v0.6.1
func (sc *SheafClient) Invalidate(regionID int) ([]int, error)
Invalidate marks a region as stale and returns the IDs of all regions that the daemon determines are transitively affected.
func (*SheafClient) PushTopology ¶ added in v0.6.1
func (sc *SheafClient) PushTopology(cr *graph.CommunityResult, refs map[string][]string) error
PushTopology converts Louvain community detection output into a sheaf_set_topology op and sends it to the daemon.
Each community maps to a region whose hash is the SHA-256 of the sorted, concatenated member node IDs. Restriction edges are derived from the refs map: any token referenced by nodes in different communities creates a boundary between those communities.
func (*SheafClient) Status ¶ added in v0.6.1
func (sc *SheafClient) Status() (SheafStatus, error)
Status returns the full sheaf status from the daemon.
type SheafStatus ¶ added in v0.6.1
type SheafStatus struct {
Generation uint64 `json:"generation"`
Valid int `json:"valid"`
Total int `json:"total"`
Defect float64 `json:"defect"`
}
SheafStatus mirrors the response from sheaf_status / sheaf_defect.
type SocketClient ¶
type SocketClient struct {
// contains filtered or unexported fields
}
SocketClient communicates with a running ley-line daemon over its Unix domain control socket ({ctrl}.sock).
func DialSocket ¶
func DialSocket(sockPath string) (*SocketClient, error)
DialSocket connects to the ley-line control socket at sockPath. The socket path is typically derived from the control path: e.g. /tmp/leyline.ctrl → /tmp/leyline.sock
func (*SocketClient) Close ¶
func (c *SocketClient) Close() error
Close closes the underlying connection. Safe to call multiple times.
func (*SocketClient) Query ¶
func (c *SocketClient) Query(sql string) ([][]any, error)
Query runs a SQL query against the active arena buffer via the `query` op. Returns the rows as [][]any.
func (*SocketClient) SendOp ¶
SendOp sends a JSON request and reads the JSON response. Both are line-delimited (newline-terminated JSON).
func (*SocketClient) SetDeadline ¶
func (c *SocketClient) SetDeadline(t time.Time) error
SetDeadline sets the read/write deadline on the underlying connection.
Source Files