Documentation
¶
Overview ¶
Package transcript provides recording and management of AI conversation transcripts.
Core types:
- Transcript: A recorded conversation with metadata and turns
- Turn: A single message in a conversation (user, assistant, or tool)
- Manager: Interface for transcript lifecycle management
- FileStore: File-based transcript storage implementation
- Searcher: Grep-based transcript search
- Viewer: Transcript display and export
Example usage:
store := transcript.NewFileStore(transcript.StoreConfig{
BaseDir: ".devflow/runs",
})
err := store.StartRun("run-123", transcript.RunMetadata{
FlowID: "ticket-to-pr",
})
err = store.RecordTurn("run-123", transcript.Turn{
Role: "assistant",
Content: "I'll implement this feature...",
})
Index ¶
- Variables
- type FileStore
- func (s *FileStore) AddCost(runID string, cost float64) error
- func (s *FileStore) BaseDir() string
- func (s *FileStore) Delete(runID string) error
- func (s *FileStore) EndRun(runID string, status RunStatus) error
- func (s *FileStore) EndRunWithError(runID string, err error) error
- func (s *FileStore) GetActive(runID string) (*Transcript, bool)
- func (s *FileStore) List(filter ListFilter) ([]Meta, error)
- func (s *FileStore) ListActive() []string
- func (s *FileStore) Load(runID string) (*Transcript, error)
- func (s *FileStore) LoadMetadata(runID string) (*Meta, error)
- func (s *FileStore) RecordToolCall(runID string, tc ToolCall) error
- func (s *FileStore) RecordTurn(runID string, turn Turn) error
- func (s *FileStore) StartRun(runID string, meta RunMetadata) error
- type ListFilter
- type Manager
- type Meta
- type RunMetadata
- type RunStatus
- type SearchOptions
- type SearchResult
- type Searcher
- func (s *Searcher) FindByDateRange(start, end time.Time) ([]Meta, error)
- func (s *Searcher) FindByFlow(flowID string) ([]Meta, error)
- func (s *Searcher) FindByStatus(status RunStatus) ([]Meta, error)
- func (s *Searcher) FindByTokenRange(minIn, maxIn, minOut, maxOut int) ([]Meta, error)
- func (s *Searcher) RunStats(filter ListFilter) (*Statistics, error)
- func (s *Searcher) SearchContent(query string, opts SearchOptions) ([]SearchResult, error)
- func (s *Searcher) TotalCost(filter ListFilter) (float64, error)
- func (s *Searcher) TotalTokens(filter ListFilter) (int, int, error)
- type Statistics
- type StoreConfig
- type ToolCall
- type Transcript
- func (t *Transcript) AddCost(cost float64)
- func (t *Transcript) AddToolCall(name string, input map[string]any, output string)
- func (t *Transcript) AddToolCallError(name string, input map[string]any, err error)
- func (t *Transcript) AddTurn(role, content string, tokens int) *Turn
- func (t *Transcript) AddTurnWithDetails(turn Turn) *Turn
- func (t *Transcript) Cancel()
- func (t *Transcript) Complete()
- func (t *Transcript) Duration() time.Duration
- func (t *Transcript) Fail(err error)
- func (t *Transcript) IsActive() bool
- func (t *Transcript) LastTurn() *Turn
- func (t *Transcript) Save(baseDir string) error
- func (t *Transcript) SetCost(cost float64)
- func (t *Transcript) TurnsByRole(role string) []Turn
- type Turn
- type Viewer
- func (v *Viewer) Diff(w io.Writer, a, b *Transcript) error
- func (v *Viewer) ExportJSON(w io.Writer, t *Transcript) error
- func (v *Viewer) ExportMarkdown(w io.Writer, t *Transcript) error
- func (v *Viewer) FormatMetaList(w io.Writer, metas []Meta) error
- func (v *Viewer) FormatStats(w io.Writer, stats *Statistics) error
- func (v *Viewer) ViewAssistantOnly(w io.Writer, t *Transcript) error
- func (v *Viewer) ViewFull(w io.Writer, t *Transcript) error
- func (v *Viewer) ViewSummary(w io.Writer, t *Transcript) error
- func (v *Viewer) ViewTurn(w io.Writer, turn Turn) error
Constants ¶
This section is empty.
Variables ¶
var ( ErrRunNotFound = errors.New("run not found") ErrRunAlreadyExists = errors.New("run already exists") ErrRunNotStarted = errors.New("run not started") ErrRunAlreadyEnded = errors.New("run already ended") )
Errors
Functions ¶
This section is empty.
Types ¶
type FileStore ¶
type FileStore struct {
// contains filtered or unexported fields
}
FileStore stores transcripts as files
func NewFileStore ¶
func NewFileStore(config StoreConfig) (*FileStore, error)
NewFileStore creates a file-based transcript store
func (*FileStore) EndRunWithError ¶
EndRunWithError completes a transcript with an error
func (*FileStore) GetActive ¶
func (s *FileStore) GetActive(runID string) (*Transcript, bool)
GetActive returns an active transcript (for monitoring)
func (*FileStore) List ¶
func (s *FileStore) List(filter ListFilter) ([]Meta, error)
List returns metadata for runs matching filter
func (*FileStore) ListActive ¶
ListActive returns all active run IDs
func (*FileStore) Load ¶
func (s *FileStore) Load(runID string) (*Transcript, error)
Load retrieves a complete transcript
func (*FileStore) LoadMetadata ¶
LoadMetadata retrieves just the metadata
func (*FileStore) RecordToolCall ¶
RecordToolCall adds a tool call to the last turn of an active transcript
func (*FileStore) RecordTurn ¶
RecordTurn adds a turn to an active transcript
type ListFilter ¶
type ListFilter struct {
FlowID string
Status RunStatus
After time.Time
Before time.Time
Limit int
}
ListFilter filters transcript listing
type Manager ¶
type Manager interface {
// Lifecycle
StartRun(runID string, metadata RunMetadata) error
RecordTurn(runID string, turn Turn) error
EndRun(runID string, status RunStatus) error
// Retrieval
Load(runID string) (*Transcript, error)
LoadMetadata(runID string) (*Meta, error)
List(filter ListFilter) ([]Meta, error)
// Maintenance
Delete(runID string) error
}
Manager is the interface for transcript operations
type Meta ¶
type Meta struct {
RunID string `json:"runId,omitempty"`
FlowID string `json:"flowId"`
NodeID string `json:"nodeId,omitempty"`
Input map[string]any `json:"input,omitempty"`
StartedAt time.Time `json:"startedAt"`
EndedAt time.Time `json:"endedAt,omitempty"`
Status RunStatus `json:"status"`
TotalTokensIn int `json:"totalTokensIn"`
TotalTokensOut int `json:"totalTokensOut"`
TotalCost float64 `json:"totalCost"`
TurnCount int `json:"turnCount"`
Error string `json:"error,omitempty"`
}
Meta contains run metadata
type RunMetadata ¶
RunMetadata is input for starting a new run
type SearchOptions ¶
type SearchOptions struct {
CaseSensitive bool
MaxResults int
Context int // Lines of context around match
}
SearchOptions configures content search
type SearchResult ¶
type SearchResult struct {
RunID string `json:"runId"`
TurnID int `json:"turnId,omitempty"`
Role string `json:"role,omitempty"`
Content string `json:"content"`
MatchLine int `json:"matchLine,omitempty"`
Match string `json:"match,omitempty"`
}
SearchResult represents a search match
type Searcher ¶
type Searcher struct {
// contains filtered or unexported fields
}
Searcher provides search capabilities over transcripts
func (*Searcher) FindByDateRange ¶
FindByDateRange returns transcripts in date range
func (*Searcher) FindByFlow ¶
FindByFlow returns transcripts for a flow
func (*Searcher) FindByStatus ¶
FindByStatus returns transcripts with status
func (*Searcher) FindByTokenRange ¶
FindByTokenRange returns transcripts within token ranges
func (*Searcher) RunStats ¶
func (s *Searcher) RunStats(filter ListFilter) (*Statistics, error)
RunStats returns statistics for matching runs
func (*Searcher) SearchContent ¶
func (s *Searcher) SearchContent(query string, opts SearchOptions) ([]SearchResult, error)
SearchContent searches transcript content using ripgrep or grep
func (*Searcher) TotalCost ¶
func (s *Searcher) TotalCost(filter ListFilter) (float64, error)
TotalCost calculates total cost for matching runs
func (*Searcher) TotalTokens ¶
func (s *Searcher) TotalTokens(filter ListFilter) (int, int, error)
TotalTokens calculates total tokens for matching runs
type Statistics ¶
type Statistics struct {
TotalRuns int
CompletedRuns int
FailedRuns int
CanceledRuns int
ActiveRuns int
TotalTokensIn int
TotalTokensOut int
TotalCost float64
AvgTokensIn int
AvgTokensOut int
AvgCost float64
}
Statistics holds aggregated run statistics
type StoreConfig ¶
type StoreConfig struct {
BaseDir string
}
StoreConfig holds configuration for transcript storage
type ToolCall ¶
type ToolCall struct {
ID string `json:"id,omitempty"`
Name string `json:"name"`
Input map[string]any `json:"input"`
Output string `json:"output,omitempty"`
Error string `json:"error,omitempty"`
}
ToolCall represents a tool/function call
type Transcript ¶
type Transcript struct {
RunID string `json:"runId"`
Metadata Meta `json:"metadata"`
Turns []Turn `json:"turns"`
}
Transcript represents a complete conversation record
func NewTranscript ¶
func NewTranscript(runID, flowID string) *Transcript
NewTranscript creates a new transcript
func (*Transcript) AddCost ¶
func (t *Transcript) AddCost(cost float64)
AddCost adds to the total cost
func (*Transcript) AddToolCall ¶
func (t *Transcript) AddToolCall(name string, input map[string]any, output string)
AddToolCall adds a tool call to the last assistant turn
func (*Transcript) AddToolCallError ¶
func (t *Transcript) AddToolCallError(name string, input map[string]any, err error)
AddToolCallError adds a failed tool call
func (*Transcript) AddTurn ¶
func (t *Transcript) AddTurn(role, content string, tokens int) *Turn
AddTurn adds a turn to the transcript
func (*Transcript) AddTurnWithDetails ¶
func (t *Transcript) AddTurnWithDetails(turn Turn) *Turn
AddTurnWithDetails adds a turn with full control over fields
func (*Transcript) Complete ¶
func (t *Transcript) Complete()
Complete marks the transcript as completed
func (*Transcript) Duration ¶
func (t *Transcript) Duration() time.Duration
Duration returns the run duration
func (*Transcript) IsActive ¶
func (t *Transcript) IsActive() bool
IsActive returns true if the run is still in progress
func (*Transcript) LastTurn ¶
func (t *Transcript) LastTurn() *Turn
LastTurn returns the last turn or nil
func (*Transcript) Save ¶
func (t *Transcript) Save(baseDir string) error
Save writes the transcript to disk
func (*Transcript) TurnsByRole ¶
func (t *Transcript) TurnsByRole(role string) []Turn
TurnsByRole returns all turns with the given role
type Turn ¶
type Turn struct {
ID int `json:"id"`
Role string `json:"role"` // system, user, assistant, tool_result
Content string `json:"content"`
TokensIn int `json:"tokensIn,omitempty"`
TokensOut int `json:"tokensOut,omitempty"`
Timestamp time.Time `json:"timestamp"`
ToolCalls []ToolCall `json:"toolCalls,omitempty"`
DurationMs int64 `json:"durationMs,omitempty"`
}
Turn represents a conversation turn
type Viewer ¶
type Viewer struct {
// contains filtered or unexported fields
}
Viewer displays transcripts
func (*Viewer) Diff ¶
func (v *Viewer) Diff(w io.Writer, a, b *Transcript) error
Diff compares two transcripts
func (*Viewer) ExportJSON ¶
func (v *Viewer) ExportJSON(w io.Writer, t *Transcript) error
ExportJSON exports to JSON format
func (*Viewer) ExportMarkdown ¶
func (v *Viewer) ExportMarkdown(w io.Writer, t *Transcript) error
ExportMarkdown exports to markdown format
func (*Viewer) FormatMetaList ¶
FormatMetaList formats a list of metadata for display
func (*Viewer) FormatStats ¶
func (v *Viewer) FormatStats(w io.Writer, stats *Statistics) error
FormatStats formats statistics for display
func (*Viewer) ViewAssistantOnly ¶
func (v *Viewer) ViewAssistantOnly(w io.Writer, t *Transcript) error
ViewAssistantOnly displays only assistant turns
func (*Viewer) ViewFull ¶
func (v *Viewer) ViewFull(w io.Writer, t *Transcript) error
ViewFull displays the complete transcript
func (*Viewer) ViewSummary ¶
func (v *Viewer) ViewSummary(w io.Writer, t *Transcript) error
ViewSummary displays a brief summary