claudetools/api/models/conversation_context.py

"""
ConversationContext model for storing Claude's conversation context.

Stores compressed summaries of conversations, sessions, and project states
for cross-machine recall and context continuity.
"""

from typing import TYPE_CHECKING, Optional

from sqlalchemy import Float, ForeignKey, Index, String, Text
from sqlalchemy.orm import Mapped, mapped_column, relationship

from .base import Base, TimestampMixin, UUIDMixin

if TYPE_CHECKING:
    from .machine import Machine
    from .project import Project
    from .session import Session


class ConversationContext(Base, UUIDMixin, TimestampMixin):
    """
    ConversationContext model for storing Claude's conversation context.

    Stores compressed, structured summaries of conversations, work sessions,
    and project states to enable Claude to recall important context across
    different machines and conversation sessions.

    Attributes:
        session_id: Foreign key to sessions (optional - not all contexts are work sessions)
        project_id: Foreign key to projects (optional)
        context_type: Type of context (session_summary, project_state, general_context)
        title: Brief title describing the context
        dense_summary: Compressed, structured summary (JSON or dense text)
        key_decisions: JSON array of important decisions made
        current_state: JSON object describing what's currently in progress
        tags: JSON array of tags for retrieval and categorization
        relevance_score: Float score for ranking relevance (default 1.0)
        machine_id: Foreign key to machines (which machine created this context)
        session: Relationship to Session model
        project: Relationship to Project model
        machine: Relationship to Machine model
    """

    __tablename__ = "conversation_contexts"

    # Foreign keys
    session_id: Mapped[Optional[str]] = mapped_column(
        String(36),
        ForeignKey("sessions.id", ondelete="SET NULL"),
        doc="Foreign key to sessions (optional - not all contexts are work sessions)"
    )

    project_id: Mapped[Optional[str]] = mapped_column(
        String(36),
        ForeignKey("projects.id", ondelete="SET NULL"),
        doc="Foreign key to projects (optional)"
    )

    machine_id: Mapped[Optional[str]] = mapped_column(
        String(36),
        ForeignKey("machines.id", ondelete="SET NULL"),
        doc="Foreign key to machines (which machine created this context)"
    )

    # Context metadata
    context_type: Mapped[str] = mapped_column(
        String(50),
        nullable=False,
        doc="Type of context: session_summary, project_state, general_context"
    )

    title: Mapped[str] = mapped_column(
        String(200),
        nullable=False,
        doc="Brief title describing the context"
    )

    # Context content
    dense_summary: Mapped[Optional[str]] = mapped_column(
        Text,
        doc="Compressed, structured summary (JSON or dense text)"
    )

    key_decisions: Mapped[Optional[str]] = mapped_column(
        Text,
        doc="JSON array of important decisions made"
    )

    current_state: Mapped[Optional[str]] = mapped_column(
        Text,
        doc="JSON object describing what's currently in progress"
    )

    # Retrieval metadata
    tags: Mapped[Optional[str]] = mapped_column(
        Text,
        doc="JSON array of tags for retrieval and categorization"
    )

    relevance_score: Mapped[float] = mapped_column(
        Float,
        default=1.0,
        server_default="1.0",
        doc="Float score for ranking relevance (default 1.0)"
    )

    # Relationships
    session: Mapped[Optional["Session"]] = relationship(
        "Session",
        doc="Relationship to Session model"
    )

    project: Mapped[Optional["Project"]] = relationship(
        "Project",
        doc="Relationship to Project model"
    )

    machine: Mapped[Optional["Machine"]] = relationship(
        "Machine",
        doc="Relationship to Machine model"
    )

    # Indexes
    __table_args__ = (
        Index("idx_conversation_contexts_session", "session_id"),
        Index("idx_conversation_contexts_project", "project_id"),
        Index("idx_conversation_contexts_machine", "machine_id"),
        Index("idx_conversation_contexts_type", "context_type"),
        Index("idx_conversation_contexts_relevance", "relevance_score"),
    )

    def __repr__(self) -> str:
        """String representation of the conversation context."""
        return f"<ConversationContext(title='{self.title}', type='{self.context_type}', relevance={self.relevance_score})>"