Documentation
¶
Index ¶
- func DetectDataFlowEdges(g *TraceGraph, events []ingest.Event, windowSize int)
- func InputShape(toolName string, input map[string]interface{}) map[string]string
- func NodeID(toolName string, shape map[string]string) uint64
- func PreprocessBashCommand(cmd string) string
- func ScorePattern(p Pattern) float64
- func ScorePatternWithDataFlow(p Pattern, dataFlowEdgeCount int) float64
- type Edge
- type HotPath
- type Node
- type Parameter
- type Pattern
- type PatternStep
- type RankedHotPath
- type Token
- type TraceGraph
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DetectDataFlowEdges ¶ added in v0.2.1
func DetectDataFlowEdges(g *TraceGraph, events []ingest.Event, windowSize int)
DetectDataFlowEdges annotates existing graph edges with data-flow information.
func InputShape ¶
InputShape produces a structural fingerprint of a tool's input. For Bash: tokenizes the command and replaces variable tokens with {VAR}. For other tools: replaces values with type tags ({STRING}, {NUMBER}, etc.).
func PreprocessBashCommand ¶ added in v0.2.2
PreprocessBashCommand strips shell noise from a command before fingerprinting. It removes cd prefixes, env var prefixes, timeout prefixes, pipe chains (keeping only the first command), and output redirections. The goal is to isolate the core tool invocation for structural matching.
func ScorePattern ¶
ScorePattern evaluates confidence that a pattern can be compiled deterministically. Returns a float64 in [0, 1]. Scores >= threshold route to deterministic backend.
func ScorePatternWithDataFlow ¶ added in v0.2.1
ScorePatternWithDataFlow is like ScorePattern but adds a bonus for data-flow edges. Each data-flow edge adds +0.1, capped at +0.3.
Types ¶
type Edge ¶
type Edge struct {
From, To uint64 // node IDs
Weight int // number of times this transition observed
SessionIDs []string // which sessions contributed
SessionWeights map[string]int // per-session transition counts
DataFlow bool // true if output of From feeds into input of To
FlowTokens []string // shared tokens indicating data flow
}
Edge represents a transition between two nodes.
type HotPath ¶
type HotPath struct {
NodeIDs []uint64 // ordered sequence of node IDs
Frequency int // number of sessions where this exact path appears
Score int // combined score: sum of per-session bottleneck counts
SessionIDs []string // contributing sessions
}
HotPath represents a frequently-traversed sequence of nodes in the trace graph.
func FindHotPaths ¶
func FindHotPaths(g *TraceGraph, minFrequency, minLength, maxLength int) []HotPath
FindHotPaths finds frequently-traversed subgraphs using DFS with session intersection.
type Node ¶
type Node struct {
ToolName string // e.g. "Bash", "Read", "Edit"
InputShape map[string]string // structural fingerprint
ID uint64 // hash of (ToolName, InputShape)
}
Node represents a unique tool-call shape in the trace graph.
type Parameter ¶
type Parameter struct {
Name string // e.g. "NAMESPACE", "FILE_PATH", "ARG_1"
Position int // token position in the command
Values []string // observed concrete values across instances
}
Parameter represents a variable extracted from diffing multiple instances.
func CollectUniqueParams ¶
func CollectUniqueParams(steps []PatternStep) []Parameter
CollectUniqueParams gathers unique parameters across all steps, preserving order.
type Pattern ¶
type Pattern struct {
Steps []PatternStep
Frequency int
SessionIDs []string
}
Pattern is a fully parameterized hot path ready for compilation.
func Parameterize ¶
func Parameterize(hotPaths []HotPath, events []ingest.Event, g *TraceGraph) []Pattern
Parameterize takes hot paths and raw events, aligns instances to the node sequence, and diffs tool inputs to extract parameters.
func RoutePatterns ¶
RoutePatterns splits patterns into deterministic and LLM batches based on confidence scoring.
type PatternStep ¶
type PatternStep struct {
ToolName string
Template string // command with $PARAM placeholders
Parameters []Parameter // extracted parameters
NodeID uint64
}
PatternStep is one step in a parameterized pattern.
type RankedHotPath ¶ added in v0.2.1
type RankedHotPath struct {
HotPath
EstimatedTokenCost int // len(NodeIDs) * 200
CompilationValue int // Frequency * EstimatedTokenCost
}
RankedHotPath is a HotPath with computed compilation value metrics.
func RankHotPaths ¶ added in v0.2.1
func RankHotPaths(paths []HotPath) []RankedHotPath
RankHotPaths computes compilation value for each hot path and returns them sorted by CompilationValue descending. The caller applies a top-N cut.
type Token ¶
type Token struct {
Value string // the raw token text
Literal bool // true = keep as-is in template; false = parameterizable
}
Token represents a single token from a parsed Bash command.
func TokenizeBashCommand ¶
TokenizeBashCommand splits a Bash command into tokens and classifies each as literal (structural) or variable (parameterizable).
Flag handling: any --long-flag is kept literal. If the next token is not itself a flag, it's treated as the flag's value (variable). This covers most CLI tools without needing a per-tool allow-list. Short flags (-x) are treated as literal boolean flags; known short value flags (-n, -f, etc.) consume the next token as a value.
Splitting uses shellFields which respects double/single quoting, so "foo bar" stays as one token.
type TraceGraph ¶
type TraceGraph struct {
Nodes map[uint64]*Node
Edges map[uint64]map[uint64]*Edge // adjacency list: from -> to -> edge
}
TraceGraph is a directed graph of tool-call sequences.
func BuildGraph ¶
func BuildGraph(events []ingest.Event) *TraceGraph
BuildGraph constructs a TraceGraph from a flat list of events. Events are grouped by session and sorted by timestamp within each session. Only post_tool_use events contribute nodes and edges.
Source Files