prism-models 0.1.0__py3-none-any.whl

prism_models/__init__.py

@@ -0,0 +1,45 @@
+"""Data models for the Prism RAG system."""
+
+__version__ = "0.1.0"
+
+
+from prism_models.agent_profile import Agent, AgentProfile, AgentProfileStatus, Profile, ProfileCollectionAccess
+from prism_models.base import POSTGRES_NAMING_CONVENTION, Base, BaseModel, TimestampMixin
+from prism_models.chat import Contact, Conversation, ConversationMessage, ConversationMessageMetadata
+from prism_models.content import Chunk, ChunkConfig, Collection, CollectionDocument, Document, IntegrationConfig, QAPair, Source, Vector
+from prism_models.feedback import Augmentation, Feedback, FeedbackAnalysis, FeedbackConfidence, FeedbackStatus, FeedbackType
+from prism_models.qdrant import QdrantVectorPayload, DestinationVectorPayload, PydanticType
+
+__all__ = [
+    "POSTGRES_NAMING_CONVENTION",
+    "Agent",
+    "AgentProfile",
+    "AgentProfileStatus",
+    "Augmentation",
+    "Base",
+    "BaseModel",
+    "Chunk",
+    "ChunkConfig",
+    "Collection",
+    "CollectionDocument",
+    "Contact",
+    "Conversation",
+    "ConversationMessage",
+    "ConversationMessageMetadata",
+    "DestinationVectorPayload",
+    "Document",
+    "Feedback",
+    "FeedbackAnalysis",
+    "FeedbackConfidence",
+    "FeedbackStatus",
+    "FeedbackType",
+    "IntegrationConfig",
+    "Profile",
+    "ProfileCollectionAccess",
+    "PydanticType",
+    "QAPair",
+    "QdrantVectorPayload",
+    "Source",
+    "TimestampMixin",
+    "Vector",
+]

prism_models/agent_profile.py

@@ -0,0 +1,101 @@
+"""Profile model for storing user profile information."""
+
+from datetime import datetime
+from enum import Enum
+
+from sqlalchemy import TIMESTAMP, Boolean
+from sqlalchemy import Enum as SAEnum
+from sqlalchemy import ForeignKey, Integer, String, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql.sqltypes import Text
+
+from prism_models.base import BaseModel
+from prism_models.content import Collection
+
+
+class Profile(BaseModel):
+    """
+    Profile model for organizing prompt variants by team/use case.
+
+    Profiles allow admins to create different prompt variations for different
+    teams or scenarios (e.g., "marketing_aggressive", "support_friendly", "default").
+    Each profile allows configuration of multiple agents.
+
+    Relationships:
+        - profile_prompts: One-to-many with ProfilePrompt
+        - agent_profiles: One-to-many with AgentProfile
+        - conversation_profiles: One-to-many with ConversationProfile
+    """
+
+    name: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
+    description: Mapped[str | None] = mapped_column(String(1024))
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+
+    __table_args__ = (UniqueConstraint("name", name="uq_profile_name"),)
+
+    def __repr__(self) -> str:
+        return f"<Profile(id={self.id}, name='{self.name}', active={self.is_active})>"
+
+
+class Agent(BaseModel):
+    """Agent model for storing agent information."""
+
+    name: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
+    display_name: Mapped[str | None] = mapped_column(String(255))
+    description: Mapped[str | None] = mapped_column(String(1024))
+
+    __table_args__ = (
+        UniqueConstraint("name", name="uq_agent_name"),
+        UniqueConstraint("display_name", name="uq_agent_display_name"),
+    )
+
+    def __repr__(self) -> str:
+        return f"<Agent(id={self.id}, name='{self.name}')>"
+
+
+class AgentProfileStatus(str, Enum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    PREVIEW = "preview"
+
+
+class AgentProfile(BaseModel):
+    """AgentProfile model for storing agent profile information."""
+
+    agent_id: Mapped[int] = mapped_column(Integer, ForeignKey("agent.id"), nullable=False, index=True)
+    profile_id: Mapped[int] = mapped_column(Integer, ForeignKey("profile.id"), nullable=False, index=True)
+    version: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
+    status: Mapped[AgentProfileStatus] = mapped_column(
+        SAEnum(AgentProfileStatus, name="agent_profile_status"),
+        default=AgentProfileStatus.PREVIEW,
+        nullable=False,
+    )
+    is_default: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    prompt: Mapped[str | None] = mapped_column(Text)
+
+    # NOT SURE IF WE NEED THIS could lead to N+1 queries
+    # TODO: Add relationship if needed
+    # agent: Mapped["Agent"] = relationship(back_populates="profile")
+    # profile: Mapped["Profile"] = relationship(back_populates="agent")
+
+
+class ProfileCollectionAccess(BaseModel):
+    """ProfileCollectionAccess model for storing profile collection access information."""
+
+    profile_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("profile.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    collection_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("collection.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    access_granted_at: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now(), nullable=True)
+    
+    collection: Mapped["Collection"] = relationship()
+
+    __table_args__ = (UniqueConstraint("profile_id", "collection_id", name="uq_profile_collection"),)

prism_models/base.py

@@ -0,0 +1,75 @@
+from datetime import UTC, datetime
+
+from sqlalchemy import Column, DateTime, Integer, MetaData, func
+from sqlalchemy.orm import Mapped, declarative_base, declared_attr, mapped_column
+
+# PostgreSQL naming convention for consistent constraint names
+POSTGRES_NAMING_CONVENTION = {
+    "ix": "%(column_0_label)s_idx",
+    "uq": "%(table_name)s_%(column_0_name)s_key",
+    "ck": "%(table_name)s_%(constraint_name)s_check",
+    "fk": "%(table_name)s_%(column_0_name)s_fkey",
+    "pk": "%(table_name)s_pkey",
+}
+
+metadata = MetaData(naming_convention=POSTGRES_NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
+
+
+class TimestampMixin:
+    """
+    Mixin for automatic timestamp fields using database-level defaults.
+    """
+
+    # Use server_default to make the database the single source of truth.
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        server_onupdate=func.now(),
+        nullable=False,
+    )
+
+
+class SoftDeleteMixin:
+    """
+    Mixin to add soft delete functionality to a model.
+    """
+
+    deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    def soft_delete(self):
+        """Mark the object as deleted."""
+        if self.deleted_at is None:
+            self.deleted_at = datetime.now(UTC)
+
+    def undelete(self):
+        """Mark the object as not deleted."""
+        self.deleted_at = None
+
+
+class ChatSchemaMixin:
+    pass
+
+
+class BaseModel(Base, TimestampMixin, SoftDeleteMixin):
+    """Base model with common fields for all entities."""
+
+    __abstract__ = True
+
+    id = Column(Integer, primary_key=True, index=True)
+
+    @declared_attr.directive
+    def __tablename__(cls):
+        """Auto-generate table name from class name in snake_case (singular)."""
+        import re
+
+        # Convert CamelCase to snake_case
+        name = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", cls.__name__)
+        return re.sub("([a-z0-9])([A-Z])", r"\1_\2", name).lower()
+
+    def __repr__(self):
+        """String representation for debugging."""
+        return f"<{self.__class__.__name__}(id={self.id})>"

prism_models/chat.py

@@ -0,0 +1,349 @@
+import uuid
+from enum import Enum as PyEnum
+
+from sqlalchemy import Boolean, CheckConstraint, Column, Enum, ForeignKey, Index, Integer, String, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from prism_models.base import BaseModel, ChatSchemaMixin
+
+
+class Gender(PyEnum):
+    MALE = "MALE"
+    FEMALE = "FEMALE"
+
+
+class ContactStatus(PyEnum):
+    ACTIVE = "ACTIVE"
+    INACTIVE = "INACTIVE"
+    APPROVAL_PENDING = "APPROVAL_PENDING"
+    MERGED = "MERGED"
+
+
+class ContactSource(PyEnum):
+    GRID = "GRID"
+    CRM = "CRM"
+    EXTERNAL = "EXTERNAL"
+
+
+class ConversationType(PyEnum):
+    TRAVEL_GUIDE = "TRAVEL_GUIDE"
+    MSA_CHAT = "MSA_CHAT"
+
+
+class MessageRole(PyEnum):
+    USER = "USER"
+    ASSISTANT = "ASSISTANT"
+    SYSTEM = "SYSTEM"
+
+
+class MessageStatus(PyEnum):
+    PENDING = "PENDING"
+    PROCESSING = "PROCESSING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+
+
+class MessageType(PyEnum):
+    TEXT = "TEXT"
+
+
+class Contact(ChatSchemaMixin, BaseModel):
+    """
+    Contact model for chat participants.
+
+    Represents individuals who can participate in conversations within the chat system.
+    Each contact can have multiple conversations and maintains their profile information
+    including personal details and CRM integration data.
+
+    Relationships:
+        - conversations: One-to-many relationship with Conversation model
+    """
+
+    email = Column(String(300), nullable=True)
+
+    first_name = Column(String(100), nullable=False)
+    middle_name = Column(String(100), nullable=True)
+    last_name = Column(String(100), nullable=False)
+
+    primary_phone = Column(String(45), nullable=True)
+
+    gender: Mapped[Gender | None] = mapped_column(Enum(Gender), nullable=True)
+
+    status: Mapped[ContactStatus | None] = mapped_column(Enum(ContactStatus), nullable=True)
+    source: Mapped[ContactSource] = mapped_column(Enum(ContactSource), nullable=False)
+
+    grid_contact_id = Column(Integer, nullable=True)
+
+    crm_contact_guid = Column(String(36), nullable=True)
+
+    account_id = Column(String(36), nullable=True)
+
+    conversations = relationship("Conversation", back_populates="contact", cascade="all, delete-orphan")
+
+
+class Conversation(ChatSchemaMixin, BaseModel):
+    """
+    Conversation model for chat sessions.
+
+    Represents a conversation thread between a contact and the system.
+    Each conversation contains multiple messages and maintains session state.
+
+    Relationships:
+        - contact: Many-to-one relationship with Contact model
+        - messages: One-to-many relationship with ConversationMessage model
+    """
+
+    uuid = Column(UUID(as_uuid=True), default=uuid.uuid4, nullable=False, unique=True, index=True)
+    title = Column(String(255), nullable=True)
+    contact_id = Column(Integer, ForeignKey("contact.id"), nullable=False)
+    is_active = Column(Boolean, default=True, nullable=False)
+    conversation_type: Mapped[ConversationType] = mapped_column(Enum(ConversationType), nullable=False)
+
+    is_audio_analysis = Column(Boolean, default=False, nullable=False)
+
+    profile_id = Column(Integer, ForeignKey("profile.id"), nullable=True)
+    preview_mode = Column(Boolean, default=False, nullable=False)
+
+    # Storage links for simulation artifacts (optional)
+    audio_file_url = Column(String(1024), nullable=True)
+    transcription_json_url = Column(String(1024), nullable=True)
+    repaired_json_url = Column(String(1024), nullable=True)
+
+    contact = relationship("Contact", back_populates="conversations")
+    messages = relationship(
+        "ConversationMessage",
+        back_populates="conversation",
+        cascade="all, delete-orphan",
+    )
+
+    conversation_comparisons = relationship(
+        "ConversationCompare",
+        back_populates="conversation",
+        cascade="all, delete-orphan",
+        order_by="ConversationCompare.question_index",
+    )
+
+    profile = relationship("Profile")
+
+
+class ConversationMessage(ChatSchemaMixin, BaseModel):
+    """
+    ConversationMessage model for individual chat messages.
+
+    Represents individual messages within a conversation thread. Messages are ordered
+    by sequence number and can be from users, assistants, or system. Each message
+    tracks its processing status and can contain LLM response data.
+
+    Relationships:
+        - conversation: Many-to-one relationship with Conversation model
+        - message_metadata: One-to-one relationship with ConversationMessageMetadata model
+
+    Constraints:
+        - Unique constraint on (conversation_id, sequence_number) ensures proper ordering
+        - Check constraint ensures sequence_number >= 0
+    """
+
+    content = Column(Text, nullable=False)
+    conversation_id = Column(Integer, ForeignKey("conversation.id"), nullable=False)
+    role: Mapped[MessageRole] = mapped_column(Enum(MessageRole), nullable=False)
+    status: Mapped[MessageStatus] = mapped_column(Enum(MessageStatus), default=MessageStatus.COMPLETED, nullable=False)
+    message_type: Mapped[MessageType] = mapped_column(Enum(MessageType), default=MessageType.TEXT, nullable=False)
+    sequence_number = Column(
+        Integer,
+        CheckConstraint("sequence_number >= 0", name="ck_sequence_number_non_negative"),
+        nullable=False,
+    )
+    llm_response_data = Column(JSONB(), nullable=True)
+    is_upvoted = Column(Boolean, nullable=True, default=None)
+    is_resolved = Column(Boolean, nullable=True, default=None)
+
+    # Relationships
+    conversation = relationship("Conversation", back_populates="messages")
+    message_metadata = relationship(
+        "ConversationMessageMetadata",
+        back_populates="message",
+        uselist=False,
+        cascade="all, delete-orphan",
+    )
+    components = relationship(
+        "MessageComponent",
+        back_populates="message",
+        cascade="all, delete-orphan",
+        order_by="MessageComponent.position",
+    )
+
+    __table_args__ = (
+        Index(
+            "ix_conversation_message_conversation_sequence",
+            "conversation_id",
+            "sequence_number",
+        ),
+        Index(
+            "ix_conversation_message_conversation_created",
+            "conversation_id",
+            "created_at",
+        ),
+        Index(
+            "ix_conversation_message_llm_response_gin",
+            "llm_response_data",
+            postgresql_using="gin",
+        ),
+        UniqueConstraint(
+            "conversation_id",
+            "sequence_number",
+            name="uq_conversation_message_sequence",
+        ),
+    )
+
+    def is_user_message(self) -> bool:
+        """Check if message is from user."""
+        return self.role == MessageRole.USER
+
+    def is_assistant_message(self) -> bool:
+        """Check if message is from AI assistant."""
+        return self.role == MessageRole.ASSISTANT
+
+    def is_system_message(self) -> bool:
+        """Check if message is a system message."""
+        return self.role == MessageRole.SYSTEM
+
+    def is_completed(self) -> bool:
+        """Check if message processing is completed."""
+        return self.status == MessageStatus.COMPLETED
+
+    def is_failed(self) -> bool:
+        """Check if message processing failed."""
+        return self.status == MessageStatus.FAILED
+
+
+class MessageComponent(ChatSchemaMixin, BaseModel):
+    """
+    MessageComponent represents a UI-renderable block (e.g., entry requirement, place list)
+    attached to a single ConversationMessage.
+    Allows each message to contain one or more UI components, rendered in order.
+    """
+
+    component_type: Mapped[str] = mapped_column(String, nullable=False)
+    payload: Mapped[dict] = mapped_column(JSONB(), nullable=False)
+    position: Mapped[int] = mapped_column(Integer, nullable=False)
+
+    message_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("conversation_message.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    message = relationship("ConversationMessage", back_populates="components")
+
+    __table_args__ = (
+        Index("ix_message_component_message_id", "message_id"),
+        Index("ix_message_component_position", "message_id", "position"),
+        UniqueConstraint(
+            "message_id",
+            "position",
+            name="uq_message_component_position",
+        ),
+    )
+
+
+class ConversationMessageMetadata(ChatSchemaMixin, BaseModel):
+    """
+    Metadata model for RAG-specific message analytics and processing information.
+
+    Stores performance metrics, model information, and retrieval context for each message.
+    This data is essential for monitoring system performance, token usage, and
+    improving RAG system effectiveness.
+
+    Relationships:
+        - message: One-to-one relationship with ConversationMessage model
+
+    Constraints:
+        - Check constraints ensure non-negative values for token counts and processing time
+        - Unique constraint on message_id ensures one metadata record per message
+    """
+
+    message_id = Column(Integer, ForeignKey("conversation_message.id"), nullable=False, unique=True)
+    model_name = Column(String(100), nullable=True)
+    token_count_input = Column(
+        Integer,
+        CheckConstraint("token_count_input >= 0", name="ck_token_count_input_non_negative"),
+        nullable=True,
+    )
+    token_count_output = Column(
+        Integer,
+        CheckConstraint("token_count_output >= 0", name="ck_token_count_output_non_negative"),
+        nullable=True,
+    )
+    processing_time_ms = Column(
+        Integer,
+        CheckConstraint("processing_time_ms >= 0", name="ck_processing_time_non_negative"),
+        nullable=True,
+    )
+    retrieval_context = Column(JSONB(), nullable=True)
+
+    # Relationships
+    message = relationship("ConversationMessage", back_populates="message_metadata")
+
+    __table_args__ = (
+        Index(
+            "ix_conversation_message_metadata_retrieval_gin",
+            "retrieval_context",
+            postgresql_using="gin",
+        ),
+    )
+
+    def calculate_total_tokens(self) -> int:
+        """Calculate total tokens used (input + output)."""
+        input_tokens = self.token_count_input or 0
+        output_tokens = self.token_count_output or 0
+        return int(input_tokens + output_tokens)
+
+
+class ConversationCompare(ChatSchemaMixin, BaseModel):
+    """
+    Stores a single QA comparison for a conversation:
+      - the user's question (normalized),
+      - the MSA agent's answer (ground truth from transcript),
+      - the AI assistant's answer (simulated reply).
+
+    Uniqueness:
+      One row per (conversation_id, question_index).
+    """
+
+    conversation_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("conversation.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    question_index: Mapped[int] = mapped_column(
+        Integer,
+        CheckConstraint("question_index >= 0", name="ck_sim_compare_qidx_non_negative"),
+        nullable=False,
+    )
+
+    question_text: Mapped[str] = mapped_column(Text, nullable=False)
+    msa_answer_text: Mapped[str | None] = mapped_column(Text, nullable=True)
+    ai_answer_text: Mapped[str | None] = mapped_column(Text, nullable=True)
+    msa_speaker_label: Mapped[str | None] = mapped_column(String(32), nullable=True)
+
+    conversation = relationship("Conversation", back_populates="conversation_comparisons")
+
+    __table_args__ = (
+        UniqueConstraint(
+            "conversation_id",
+            "question_index",
+            name="uq_sim_compare_conversation_qidx",
+        ),
+        Index(
+            "ix_sim_compare_conversation_created",
+            "conversation_id",
+            "created_at",
+        ),
+        Index(
+            "ix_sim_compare_conversation_sequence",
+            "conversation_id",
+            "question_index",
+        ),
+    )

prism_models/config.py

@@ -0,0 +1,37 @@
+from enum import Enum
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Environment(str, Enum):
+    """Environment types."""
+
+    DEVELOPMENT = "development"
+    STAGING = "staging"
+    PRODUCTION = "production"
+
+
+class Settings(BaseSettings):
+    """Minimal configuration for prism-models database operations."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    PG_DATABASE_URL: str = "postgresql+asyncpg://user:password@host"
+    environment: Environment = Environment.DEVELOPMENT
+
+    @property
+    def PG_DATABASE_URL_PRISM(self) -> str:
+        """Get the Prism database URL."""
+        return self.PG_DATABASE_URL + "/prism"
+
+    @property
+    def is_development(self) -> bool:
+        """Check if running in development environment."""
+        return self.environment == Environment.DEVELOPMENT
+
+
+settings = Settings()