conversations

package
v0.3.28-beta Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 5, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package conversations provides conversation management functionality for kodelet. It offers high-level services for storing, retrieving, querying, and managing conversation records with support for filtering, pagination, and statistics.

Index

Constants

View Source
const (
	DefaultMaxToolResultCharacters = 2000
	DefaultMaxToolResultBytes      = 100 * 1024
	ToolResultTruncationMarker     = "\n[ ... omitted remaining lines to make summarizing use less tokens ... ]"
)

Variables

View Source
var ErrCWDConflict = errors.New("requested cwd does not match conversation cwd")

ErrCWDConflict is returned when a caller requests a cwd that conflicts with an existing conversation binding.

Functions

func CurrentWorkingDirectory

func CurrentWorkingDirectory() (string, error)

CurrentWorkingDirectory returns the canonical current process working directory.

func GetMostRecentConversationID

func GetMostRecentConversationID(ctx context.Context) (string, error)

GetMostRecentConversationID returns the ID of the most recent conversation

func NormalizeCWD

func NormalizeCWD(path string) (string, error)

NormalizeCWD resolves a path into a canonical absolute directory path.

func RenderMarkdown

func RenderMarkdown(
	messages []StreamableMessage,
	toolResults map[string]tooltypes.StructuredToolResult,
	opts MarkdownOptions,
) string

RenderMarkdown converts conversation entries into markdown.

Types

type CWDResolution

type CWDResolution struct {
	CWD            string
	Locked         bool
	LegacyRecord   bool
	ConversationID string
	Record         *convtypes.ConversationRecord
}

CWDResolution captures the resolved execution directory for a conversation.

func ResolveCWD

func ResolveCWD(
	ctx context.Context,
	store ConversationStore,
	conversationID string,
	requestedCWD string,
	defaultCWD string,
	requireExisting bool,
) (*CWDResolution, error)

ResolveCWD determines the effective cwd for a new or existing conversation. When requireExisting is false, a missing conversation is treated as a new one.

type Config

type Config struct {
	StoreType string // "sqlite"
	BasePath  string // Base storage path
}

Config holds configuration for the conversation store

func DefaultConfig

func DefaultConfig() (*Config, error)

DefaultConfig returns a default configuration

type ConversationService

type ConversationService struct {
	// contains filtered or unexported fields
}

ConversationService provides high-level conversation operations

func GetDefaultConversationService

func GetDefaultConversationService(ctx context.Context) (*ConversationService, error)

GetDefaultConversationService returns a service with the default store

func NewConversationService

func NewConversationService(store ConversationStore) *ConversationService

NewConversationService creates a new conversation service

func (*ConversationService) Close

func (s *ConversationService) Close() error

Close closes the underlying store

func (*ConversationService) DeleteConversation

func (s *ConversationService) DeleteConversation(ctx context.Context, id string) error

DeleteConversation deletes a conversation

func (*ConversationService) ForkConversation

func (s *ConversationService) ForkConversation(ctx context.Context, id string) (*GetConversationResponse, error)

ForkConversation duplicates a conversation into a new conversation record while resetting token and cost usage counters and preserving context window data.

func (*ConversationService) GetConversation

func (s *ConversationService) GetConversation(ctx context.Context, id string) (*GetConversationResponse, error)

GetConversation retrieves a specific conversation with all its data

func (*ConversationService) GetToolResult

func (s *ConversationService) GetToolResult(ctx context.Context, conversationID, toolCallID string) (*GetToolResultResponse, error)

GetToolResult retrieves a specific tool result from a conversation

func (*ConversationService) ListConversations

ListConversations retrieves conversations with filtering and pagination

type ConversationServiceInterface

type ConversationServiceInterface interface {
	ListConversations(ctx context.Context, req *ListConversationsRequest) (*ListConversationsResponse, error)
	GetConversation(ctx context.Context, id string) (*GetConversationResponse, error)
	GetToolResult(ctx context.Context, conversationID, toolCallID string) (*GetToolResultResponse, error)
	ForkConversation(ctx context.Context, id string) (*GetConversationResponse, error)
	DeleteConversation(ctx context.Context, id string) error
	Close() error
}

ConversationServiceInterface defines the interface for conversation operations

type ConversationStatistics

type ConversationStatistics struct {
	TotalConversations int     `json:"totalConversations"`
	TotalMessages      int     `json:"totalMessages"`
	TotalTokens        int     `json:"totalTokens"`
	TotalCost          float64 `json:"totalCost"`
	InputTokens        int     `json:"inputTokens"`
	OutputTokens       int     `json:"outputTokens"`
	CacheReadTokens    int     `json:"cacheReadTokens"`
	CacheWriteTokens   int     `json:"cacheWriteTokens"`
	InputCost          float64 `json:"inputCost"`
	OutputCost         float64 `json:"outputCost"`
	CacheReadCost      float64 `json:"cacheReadCost"`
	CacheWriteCost     float64 `json:"cacheWriteCost"`
}

ConversationStatistics represents conversation statistics

type ConversationStore

type ConversationStore interface {
	// Basic CRUD operations
	Save(ctx context.Context, record conversations.ConversationRecord) error
	Load(ctx context.Context, id string) (conversations.ConversationRecord, error)
	Delete(ctx context.Context, id string) error

	// Advanced query operations
	Query(ctx context.Context, options conversations.QueryOptions) (conversations.QueryResult, error)

	// Lifecycle methods
	Close() error // Close doesn't need context
}

ConversationStore defines the interface for conversation persistence

func GetConversationStore

func GetConversationStore(ctx context.Context) (ConversationStore, error)

GetConversationStore is a convenience function that creates a store with default configuration

func NewConversationStore

func NewConversationStore(ctx context.Context, config *Config) (ConversationStore, error)

NewConversationStore creates the appropriate ConversationStore implementation based on the provided configuration

type ConversationStreamer

type ConversationStreamer struct {
	// contains filtered or unexported fields
}

ConversationStreamer handles streaming conversation data in structured JSON format

func NewConversationStreamer

func NewConversationStreamer(service ConversationServiceInterface) *ConversationStreamer

NewConversationStreamer creates a new conversation streamer

func (*ConversationStreamer) RegisterMessageParser

func (cs *ConversationStreamer) RegisterMessageParser(provider string, parser MessageParser)

RegisterMessageParser registers a message parser for a specific provider

func (*ConversationStreamer) StreamLiveUpdates

func (cs *ConversationStreamer) StreamLiveUpdates(
	ctx context.Context,
	conversationID string,
	streamOpts StreamOpts,
) error

StreamLiveUpdates watches for conversation updates and streams entries based on options

type GetConversationResponse

type GetConversationResponse struct {
	ID           string                                `json:"id"`
	CWD          string                                `json:"cwd,omitempty"`
	CreatedAt    time.Time                             `json:"createdAt"`
	UpdatedAt    time.Time                             `json:"updatedAt"`
	Provider     string                                `json:"provider"`
	Summary      string                                `json:"summary,omitempty"`
	Usage        llmtypes.Usage                        `json:"usage"`
	RawMessages  json.RawMessage                       `json:"rawMessages"`
	Metadata     map[string]any                        `json:"metadata,omitempty"`
	ToolResults  map[string]tools.StructuredToolResult `json:"toolResults,omitempty"`
	MessageCount int                                   `json:"messageCount"`
}

GetConversationResponse represents the response from getting a conversation

type GetToolResultResponse

type GetToolResultResponse struct {
	ToolCallID string                     `json:"toolCallId"`
	Result     tools.StructuredToolResult `json:"result"`
}

GetToolResultResponse represents the response from getting a tool result

type ListConversationsRequest

type ListConversationsRequest struct {
	StartDate  *time.Time `json:"startDate,omitempty"`
	EndDate    *time.Time `json:"endDate,omitempty"`
	SearchTerm string     `json:"searchTerm,omitempty"`
	Limit      int        `json:"limit,omitempty"`
	Offset     int        `json:"offset,omitempty"`
	SortBy     string     `json:"sortBy,omitempty"`
	SortOrder  string     `json:"sortOrder,omitempty"`
}

ListConversationsRequest represents a request to list conversations

type ListConversationsResponse

type ListConversationsResponse struct {
	Conversations []conversations.ConversationSummary `json:"conversations"`
	Total         int                                 `json:"total"`
	Limit         int                                 `json:"limit"`
	Offset        int                                 `json:"offset"`
	HasMore       bool                                `json:"hasMore"`
	Stats         *ConversationStatistics             `json:"stats,omitempty"`
}

ListConversationsResponse represents the response from listing conversations

type MarkdownOptions

type MarkdownOptions struct {
	TruncateToolResults bool
	MaxToolResultChars  int
	MaxToolResultBytes  int
	ExcludeThinking     bool
}

MarkdownOptions controls markdown rendering for conversation messages.

type MessageParser

type MessageParser func(rawMessages json.RawMessage, metadata map[string]any, toolResults map[string]tools.StructuredToolResult) ([]StreamableMessage, error)

MessageParser is a function type that can parse provider-specific raw messages into streamable format

type StreamEntry

type StreamEntry struct {
	Kind           string `json:"kind"`                      // "text", "tool-use", "tool-result", "thinking"
	Content        string `json:"content,omitempty"`         // Text content for text and thinking
	ToolName       string `json:"tool_name,omitempty"`       // Tool name for tool-use and tool-result
	Input          string `json:"input,omitempty"`           // JSON input for tool-use
	Result         string `json:"result,omitempty"`          // Tool execution result for tool-result
	Role           string `json:"role"`                      // "user", "assistant", "system"
	ToolCallID     string `json:"tool_call_id,omitempty"`    // For matching tool calls to results
	ConversationID string `json:"conversation_id,omitempty"` // ID of the conversation this entry belongs to
}

StreamEntry represents a single stream entry in the unified JSON format

type StreamOpts

type StreamOpts struct {
	Interval       time.Duration
	IncludeHistory bool
	HistoryOnly    bool
	New            bool
}

StreamOpts contains options for streaming conversation data

type StreamableMessage

type StreamableMessage struct {
	Kind       string // "text", "tool-use", "tool-result", "thinking"
	Role       string // "user", "assistant", "system"
	Content    string // Text content
	RawItem    json.RawMessage
	ToolName   string // For tool use/result
	ToolCallID string // For matching tool results
	Input      string // For tool use (JSON string)
}

StreamableMessage contains parsed message data for streaming

Directories

Path Synopsis
Package sqlite provides SQLite-specific implementation for conversation storage.
Package sqlite provides SQLite-specific implementation for conversation storage.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL