1. Behavior and Context

Within the framework, these models govern how data is moved, validated, and stored.

• Schema Enforcement: Every piece of data entering the system is validated at runtime. For example, a sentiment_score is strictly enforced as a float between -1.0 and 1.0.
• Relational Mapping: Models are linked via unique identifiers. A Message is mapped to a Conversation, and a TurnTrace is explicitly linked to an assistant Message to provide a 1:1 map between a response and the reasoning that produced it.
• Serialization Logic: Models are designed for native JSON compatibility, allowing complex nested structures—such as sandbox execution logs—to be stored efficiently in modern databases like PostgreSQL (via JSONB) or MongoDB.

2. Purpose

• Data Integrity: Ensuring that conversation records remain consistent and valid across different storage providers.
• Observability: Providing the TurnTrace master record, which serves as a "Black Box" for auditing every decision an agent makes.
• Financial & Performance Auditing: Tracking exact token consumption and API latency for every individual call to an LLM.
• Debugging: Capturing granular details of sandboxed code execution, including stdout bytes, peak memory usage, and full Python tracebacks.

3. High-Level API Examples

Example: Manual Message Construction

from jazzmine.core.message_store import Message, MessageRole, Entity
import time

# Defining a structured user message
msg = Message(
    id="uuid-v4-string",
    conversation_id="session-123",
    user_id="user-789",
    role=MessageRole.USER,
    original_content="Check my last three orders",
    timestamp=int(time.time() * 1000)
)

# Creating a concept extraction record
product = Entity(
    name="iPhone 15 Pro",
    attributes=["Color: Titanium", "Storage: 256GB"]
)

4. Core Interaction Models

MessageRole (Enum)

Specifies the participant responsible for a specific message turn:

• USER: The human end-user.
• ASSISTANT: The primary AI agent.
• COLLEAGUE_ASSISTANT: A secondary specialized agent or delegate.
• SYSTEM: Internal instructions and context steering.

Entity

A structured representation of a noun or concept identified within a conversation.

• name (str): The canonical name of the entity.
• attributes (list[str]): Descriptive tags or metadata associated with the entity.

Conversation

Represents the top-level metadata for a unique chat session.

• id (str): Unique session identifier.
• user_id / agent_id: References to the owner and the handling agent.
• title: A short, human-readable summary of the interaction.

Message

The primary record of an interaction. It is updated throughout its lifecycle by the enhancer and summarizer components.

• original_content: The raw, unprocessed text.
• enhanced_message: The disambiguated version (e.g., pronouns resolved).
• explicit_context: Optional snippets of external data (RAG) provided to the turn.
• episode_id: Link to the specific interaction summary in Episodic Memory.
• is_flagged: A safety flag; if True, the message is ignored by future context windows.
• is_continuation: Tracks if the user is still on the same logical topic.
• invoked_flows / invoked_tools: Registry of the skills utilized during this turn.
• reasoning_steps: The raw internal "thoughts" of the agent before its reply.

5. Observability & Trace Models

LLMCallRecord

A granular record of a single request made to an AI model provider.

• purpose (Literal): Categorizes the call (e.g., "agent_loop", "enhancement", "script_generation").
• model (str): The specific model ID used.
• prompt_tokens / completion_tokens: Exact token accounting for cost tracking.
• latency_ms: The network/generation time in milliseconds.

ToolTrace

The definitive execution log for a task delegated to a sandbox environment.

• generation_attempts: A list of ScriptGenAttempt objects, recording LLM retries for code generation.
• final_script: The exact Python code that was physically executed.
• final_data: The structured JSON result returned from the container.
• traceback: The full Python error stack if the code crashed.
• output_bytes: Total size of data emitted to stdout (used for resource monitoring).

TurnTrace (The Master Record)

The TurnTrace is the comprehensive observability object for a single agent turn. One TurnTrace is generated for every assistant response. It aggregates all telemetry into a single queryable document.

• message_id: Foreign key to the Message that concluded the turn.
• total_tokens: Aggregate count of all tokens consumed across all LLM calls in the turn.
• total_latency_ms: Total wall-clock time from user input to agent response.
• task_emissions: List of <task> tags generated by the agent.
• tool_traces: List of every code execution performed during the turn.
• slot_events / flow_events: Tracking for parameter collection and flow state transitions.

6. Error Handling

• Validation Failures: If a storage backend attempts to load data that violates the model schema (e.g., a missing required ID or invalid Enum value), Pydantic will raise a ValidationError. This ensures corrupted data never enters the agent's reasoning loop.
• Safe Defaults: Most models use default_factory for lists and sensible defaults for scores (e.g., sentiment_score=0.0) to ensure robustness if sub-components fail.

7. Remarks

• Audit-Ready Architecture: The separation of Message and TurnTrace is intentional. While Message is optimized for display in a UI, TurnTrace is optimized for technical auditing and debugging.
• JSON Native: All models are designed to be serialized using model_dump(mode="json"), ensuring seamless compatibility with modern document-based and relational databases.