🔍 Code Extractor

A dataclass representing a single turn in a conversation, storing metadata about the exchange including input/output summaries, files, topics, and processing metrics.

Purpose

ConversationTurn serves as a structured data container for capturing all relevant information about a single exchange in a conversation. It stores both the content summaries (input and response), file references, extracted topics and key points, and performance metrics (processing time and token usage). This class is typically used in conversation management systems to maintain a history of interactions, enable conversation analysis, and support session persistence.

Source Code

class ConversationTurn:
    """Individual turn in a conversation"""
    exchange_id: str
    exchange_number: int
    timestamp: datetime
    input_summary: str
    response_summary: str
    input_file: str
    response_file: str
    topics: List[str]
    key_points: List[str]
    processing_time: float
    tokens_used: int

Parameters

Name	Type	Default	Kind
bases	-	-

Parameter Details

exchange_id: Unique identifier for this conversation turn, typically a UUID or similar unique string to distinguish this exchange from others

exchange_number: Sequential number indicating the position of this turn in the conversation (e.g., 1 for first turn, 2 for second turn)

timestamp: datetime object recording when this conversation turn occurred, used for chronological ordering and time-based analysis

input_summary: String containing a summary or the full text of the user's input/query for this turn

response_summary: String containing a summary or the full text of the system's response for this turn

input_file: File path or filename where the full input content is stored, allowing reference to complete input data

response_file: File path or filename where the full response content is stored, allowing reference to complete response data

topics: List of strings representing the main topics or themes identified in this conversation turn

key_points: List of strings capturing the important points or takeaways from this exchange

processing_time: Float value representing the time (in seconds) taken to process and generate the response

tokens_used: Integer count of tokens consumed during this exchange, relevant for API usage tracking and cost management

Return Value

As a dataclass, instantiation returns a ConversationTurn object with all specified attributes initialized. The object provides automatic __init__, __repr__, __eq__, and other methods generated by the @dataclass decorator. No explicit methods return values as this is a pure data container.

Class Interface

Attributes

Name	Type	Description	Scope
exchange_id	str	Unique identifier for this conversation turn	instance
exchange_number	int	Sequential number indicating the position of this turn in the conversation	instance
timestamp	datetime	When this conversation turn occurred	instance
input_summary	str	Summary or full text of the user's input for this turn	instance
response_summary	str	Summary or full text of the system's response for this turn	instance
input_file	str	File path where the full input content is stored	instance
response_file	str	File path where the full response content is stored	instance
topics	List[str]	List of main topics or themes identified in this conversation turn	instance
key_points	List[str]	List of important points or takeaways from this exchange	instance
processing_time	float	Time in seconds taken to process and generate the response	instance
tokens_used	int	Count of tokens consumed during this exchange	instance

Dependencies

• dataclasses
• datetime
• typing

Required Imports

from dataclasses import dataclass
from datetime import datetime
from typing import List

Usage Example

from dataclasses import dataclass
from datetime import datetime
from typing import List

@dataclass
class ConversationTurn:
    exchange_id: str
    exchange_number: int
    timestamp: datetime
    input_summary: str
    response_summary: str
    input_file: str
    response_file: str
    topics: List[str]
    key_points: List[str]
    processing_time: float
    tokens_used: int

# Create a conversation turn
turn = ConversationTurn(
    exchange_id="turn-001",
    exchange_number=1,
    timestamp=datetime.now(),
    input_summary="User asked about Python dataclasses",
    response_summary="Explained dataclass features and benefits",
    input_file="/path/to/input_001.txt",
    response_file="/path/to/response_001.txt",
    topics=["Python", "dataclasses", "programming"],
    key_points=["Dataclasses reduce boilerplate", "Auto-generate methods"],
    processing_time=1.23,
    tokens_used=450
)

# Access attributes
print(f"Turn {turn.exchange_number}: {turn.input_summary}")
print(f"Topics: {', '.join(turn.topics)}")
print(f"Processing took {turn.processing_time}s using {turn.tokens_used} tokens")

Best Practices

• This is a pure data container with no methods, so instantiation is straightforward using keyword arguments
• Always provide all required fields during instantiation as dataclasses without default values require all parameters
• Use consistent formats for exchange_id (e.g., UUID strings) to ensure uniqueness across conversations
• Ensure exchange_number is sequential and starts from 1 for proper conversation ordering
• Store actual file content in the files referenced by input_file and response_file, using these attributes only for references
• Use datetime.now() or datetime.utcnow() for timestamp to ensure accurate time tracking
• Keep topics and key_points lists concise and relevant for effective conversation analysis
• Track processing_time accurately to monitor performance and identify bottlenecks
• Monitor tokens_used for API cost management and rate limiting considerations
• Consider serializing to JSON or similar format for persistence using dataclasses.asdict() or similar utilities
• This class is immutable by default unless frozen=True is added to @dataclass decorator; consider immutability for thread safety

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class ConversationContext 72.6% similar

  A dataclass that stores comprehensive conversation context including timeline, turns, topics, insights, and references for managing rich conversational state.

  From: /tf/active/vicechatdev/e-ink-llm/conversation_context.py

• class Exchange 72.4% similar

  A dataclass representing a single exchange (input-response pair) in a conversation, storing metadata about the interaction including timing, tokens, and file information.

  From: /tf/active/vicechatdev/e-ink-llm/session_manager.py

• class ConversationState 69.9% similar

  A dataclass that represents the complete state of a conversation, including its metadata, exchanges, and lifecycle information.

  From: /tf/active/vicechatdev/e-ink-llm/session_manager.py

• class ConversationReference 64.9% similar

  A dataclass that stores a reference to a previous conversation exchange, including metadata about the reference type, content, and relevance.

  From: /tf/active/vicechatdev/e-ink-llm/conversation_context.py

• class ChatSession_v1 59.2% similar

  A dataclass representing a chat session associated with a specific text section in a document, managing conversation messages, context, and references.

  From: /tf/active/vicechatdev/vice_ai/models.py

class ConversationTurn:
    """Individual turn in a conversation"""
    exchange_id: str
    exchange_number: int
    timestamp: datetime
    input_summary: str
    response_summary: str
    input_file: str
    response_file: str
    topics: List[str]
    key_points: List[str]
    processing_time: float
    tokens_used: int