trace

Documentation

Index

• Constants
• type ArtifactManifest
• type RunMetadata
• type ToolCallRecord
• type TraceSession
  • func NewTraceSession(traceDir, provider, model string) (*TraceSession, error)
  • func (s *TraceSession) Close() error
  • func (s *TraceSession) GetRunDir() string
  • func (s *TraceSession) GetRunID() string
  • func (s *TraceSession) RecordArtifact(record ArtifactManifest) error
  • func (s *TraceSession) RecordToolCall(record ToolCallRecord) error
  • func (s *TraceSession) RecordTurn(record TurnRecord) error
• type TurnRecord

Constants

const (
	// Path violations
	LabelPathViolationAbsolute   = "path_violation_absolute"
	LabelPathViolationNested     = "path_violation_nested"
	LabelPathViolationDisallowed = "path_violation_disallowed_prefix"

	// Schema violations
	LabelSchemaEnvelopeViolation = "schema_envelope_violation"
	LabelLayoutViolation         = "layout_violation"

	// Tool call issues
	LabelToolCallValidationFailure = "tool_call_validation_failure"
	LabelToolCallUnknownTool       = "tool_call_unknown_tool"
	LabelToolCallTimeout           = "tool_call_timeout"
	LabelToolCallExecutionError    = "tool_call_execution_error"
)

Machine label constants

Types

type ArtifactManifest

type ArtifactManifest struct {
	RunID         string   `json:"run_id"`
	RelativePath  string   `json:"relative_path"`
	SizeBytes     int64    `json:"size_bytes"`
	Hash          string   `json:"hash"`          // SHA-256
	ArtifactType  string   `json:"artifact_type"` // file_edit, file_create, etc.
	MachineLabels []string `json:"machine_labels"`
	Timestamp     string   `json:"timestamp"`
}

ArtifactManifest represents filesystem outputs from a run

type RunMetadata

type RunMetadata struct {
	RunID         string            `json:"run_id"`
	Timestamp     string            `json:"timestamp"`
	Provider      string            `json:"provider"`
	Model         string            `json:"model"`
	ReasoningMode string            `json:"reasoning_mode"`
	Persona       string            `json:"persona"`
	WorkflowName  string            `json:"workflow_name"`
	WorkflowIndex int               `json:"workflow_index"`
	EnvConfig     map[string]string `json:"env_config"`
}

RunMetadata represents metadata for a single sprout invocation/run

type ToolCallRecord

type ToolCallRecord struct {
	RunID          string                 `json:"run_id"`
	TurnIndex      int                    `json:"turn_index"` // Index within turn
	ToolIndex      int                    `json:"tool_index"` // Index within turn
	ToolName       string                 `json:"tool_name"`
	Args           map[string]interface{} `json:"args"`
	ArgsNormalized map[string]interface{} `json:"args_normalized"`
	Success        bool                   `json:"success"`
	FullResult     string                 `json:"full_result"`    // Untruncated
	ModelResult    string                 `json:"model_result"`   // As model sees it
	ErrorCategory  string                 `json:"error_category"` // validation, unknown_tool, timeout, etc.
	ErrorMessage   string                 `json:"error_message"`
	MachineLabels  []string               `json:"machine_labels"`
	Timestamp      string                 `json:"timestamp"`
}

ToolCallRecord represents a single tool execution

type TraceSession

type TraceSession struct {
	RunID         string
	RunDir        string
	RunsFile      *jsonlWriter
	TurnsFile     *jsonlWriter
	ToolsFile     *jsonlWriter
	ArtifactsFile *jsonlWriter
	Metadata      RunMetadata
	IsEnabled     bool
	// contains filtered or unexported fields
}

TraceSession manages dataset collection for a single sprout run

func NewTraceSession

func NewTraceSession(traceDir, provider, model string) (*TraceSession, error)

NewTraceSession creates a new trace session

func (*TraceSession) Close

func (s *TraceSession) Close() error

Close closes all file writers

func (*TraceSession) GetRunDir

func (s *TraceSession) GetRunDir() string

GetRunDir returns the run directory path

func (*TraceSession) GetRunID

func (s *TraceSession) GetRunID() string

GetRunID returns the run ID

func (*TraceSession) RecordArtifact

func (s *TraceSession) RecordArtifact(record ArtifactManifest) error

RecordArtifact records a filesystem output

func (*TraceSession) RecordToolCall

func (s *TraceSession) RecordToolCall(record ToolCallRecord) error

RecordToolCall records a tool execution

func (*TraceSession) RecordTurn

func (s *TraceSession) RecordTurn(record TurnRecord) error

RecordTurn records a model turn

type TurnRecord

type TurnRecord struct {
	RunID              string          `json:"run_id"`
	TurnIndex          int             `json:"turn_index"`
	SystemPrompt       string          `json:"system_prompt"`
	UserPrompt         string          `json:"user_prompt"`
	UserPromptOriginal string          `json:"user_prompt_original"` // Pre-truncation
	MessagesSent       []api.Message   `json:"messages_sent"`
	ToolSchemaPayload  json.RawMessage `json:"tool_schema_payload"`
	RawResponse        string          `json:"raw_response"`
	ParsedToolCalls    []api.ToolCall  `json:"parsed_tool_calls"`
	ParserErrors       []string        `json:"parser_errors"`
	FallbackUsed       bool            `json:"fallback_used"`
	FallbackOutput     string          `json:"fallback_output"`
	MachineLabels      []string        `json:"machine_labels"`
	Timestamp          string          `json:"timestamp"`
}

TurnRecord represents a single model turn (request + response)