solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/repository/models/models_llm.txt

@@ -0,0 +1,257 @@
+## Quick Summary
+This directory contains SQLAlchemy ORM models and Pydantic schemas for database persistence in the HTTP SSE gateway. It provides models for managing chat sessions, tasks, task events, and user feedback with proper relationships and database schema definitions.
+
+## Files Overview
+- `__init__.py` - Package initialization exposing all SQLAlchemy and Pydantic models
+- `base.py` - SQLAlchemy declarative base configuration
+- `chat_task_model.py` - ChatTaskModel for storing chat tasks with session relationships
+- `feedback_model.py` - FeedbackModel for storing user feedback on tasks
+- `session_model.py` - SessionModel and Pydantic schemas for managing chat sessions
+- `task_event_model.py` - TaskEventModel for storing A2A task events with task relationships
+- `task_model.py` - TaskModel for managing tasks with event relationships and token usage tracking
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Package entry point that exposes all SQLAlchemy models and Pydantic schemas
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.models import Base, ChatTaskModel, FeedbackModel, SessionModel, CreateSessionModel, UpdateSessionModel, TaskEventModel, TaskModel`
+
+**Constants/Variables:**
+- `__all__: List[str]` - Public API exports including all models and schemas
+
+### base.py
+**Purpose:** Provides the SQLAlchemy declarative base for all models
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.models.base import Base`
+
+**Constants/Variables:**
+- `Base: DeclarativeMeta` - SQLAlchemy declarative base class for all models
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.models.base import Base
+from sqlalchemy import create_engine
+
+# Create all tables
+engine = create_engine("sqlite:///example.db")
+Base.metadata.create_all(engine)
+```
+
+### chat_task_model.py
+**Purpose:** SQLAlchemy model for storing chat tasks with session relationships
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.models.chat_task_model import ChatTaskModel`
+
+**Classes:**
+- `ChatTaskModel(Base)` - SQLAlchemy model for chat tasks
+  - `id: Column[String]` - Primary key task identifier
+  - `session_id: Column[String]` - Foreign key to sessions table with CASCADE delete (indexed)
+  - `user_id: Column[String]` - User identifier (indexed)
+  - `user_message: Column[Text]` - Optional user message content
+  - `message_bubbles: Column[Text]` - Required message bubbles data
+  - `task_metadata: Column[Text]` - Optional task metadata
+  - `created_time: Column[BigInteger]` - Creation timestamp in epoch milliseconds (indexed)
+  - `updated_time: Column[BigInteger]` - Optional update timestamp
+  - `session: relationship` - SQLAlchemy relationship to SessionModel
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.models.chat_task_model import ChatTaskModel
+from sqlalchemy.orm import sessionmaker
+
+# Create a chat task
+chat_task = ChatTaskModel(
+    id="task_123",
+    session_id="session_456",
+    user_id="user_789",
+    user_message="Hello, how can you help me?",
+    message_bubbles='[{"type": "user", "content": "Hello"}]',
+    task_metadata='{"priority": "high"}',
+    created_time=1640995200000,
+    updated_time=1640995260000
+)
+
+# Add to database
+Session = sessionmaker(bind=engine)
+db_session = Session()
+db_session.add(chat_task)
+db_session.commit()
+
+# Access related session
+session = chat_task.session
+```
+
+### feedback_model.py
+**Purpose:** SQLAlchemy model for storing user feedback on tasks
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.models.feedback_model import FeedbackModel`
+
+**Classes:**
+- `FeedbackModel(Base)` - SQLAlchemy model for user feedback
+  - `id: Column[String]` - Primary key feedback identifier
+  - `session_id: Column[String]` - Session identifier
+  - `task_id: Column[String]` - Task identifier (indexed)
+  - `user_id: Column[String]` - User identifier (indexed)
+  - `rating: Column[String]` - Feedback rating (e.g., 'up', 'down')
+  - `comment: Column[Text]` - Optional feedback comment
+  - `created_time: Column[BigInteger]` - Creation timestamp in epoch milliseconds
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.models.feedback_model import FeedbackModel
+from sqlalchemy.orm import sessionmaker
+
+# Create feedback
+feedback = FeedbackModel(
+    id="feedback_123",
+    session_id="session_456",
+    task_id="task_789",
+    user_id="user_123",
+    rating="up",
+    comment="Great response!",
+    created_time=1640995200000
+)
+
+# Add to database
+Session = sessionmaker(bind=engine)
+db_session = Session()
+db_session.add(feedback)
+db_session.commit()
+```
+
+### session_model.py
+**Purpose:** SQLAlchemy model and Pydantic schemas for managing chat sessions with chat task relationships
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.models.session_model import SessionModel, CreateSessionModel, UpdateSessionModel`
+
+**Classes:**
+- `SessionModel(Base)` - SQLAlchemy model for chat sessions
+  - `id: Column[String]` - Primary key session identifier
+  - `name: Column[String]` - Optional session name
+  - `user_id: Column[String]` - Required user identifier
+  - `agent_id: Column[String]` - Optional agent identifier
+  - `created_time: Column[BigInteger]` - Creation timestamp (auto-generated)
+  - `updated_time: Column[BigInteger]` - Last update timestamp (auto-updated)
+  - `chat_tasks: relationship` - SQLAlchemy relationship to ChatTaskModel with cascade delete
+
+- `CreateSessionModel(BaseModel)` - Pydantic model for creating sessions
+  - `id: str` - Session identifier
+  - `name: str | None` - Optional session name
+  - `user_id: str` - User identifier
+  - `agent_id: str | None` - Optional agent identifier
+  - `created_time: int` - Creation timestamp
+  - `updated_time: int` - Update timestamp
+
+- `UpdateSessionModel(BaseModel)` - Pydantic model for updating sessions
+  - `name: str | None` - Optional updated session name
+  - `agent_id: str | None` - Optional updated agent identifier
+  - `updated_time: int` - Update timestamp
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.models.session_model import SessionModel, CreateSessionModel
+from sqlalchemy.orm import sessionmaker
+
+# Create using SQLAlchemy model
+session = SessionModel(
+    id="session_123",
+    name="My Chat Session",
+    user_id="user_456",
+    agent_id="agent_789"
+)
+
+# Create using Pydantic model
+create_data = CreateSessionModel(
+    id="session_124",
+    name="Another Session",
+    user_id="user_456",
+    agent_id="agent_789",
+    created_time=1640995200000,
+    updated_time=1640995200000
+)
+
+# Access related chat tasks
+chat_tasks = session.chat_tasks  # Returns list of ChatTaskModel instances
+```
+
+### task_event_model.py
+**Purpose:** SQLAlchemy model for storing A2A task events with task relationships
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.models.task_event_model import TaskEventModel`
+
+**Classes:**
+- `TaskEventModel(Base)` - SQLAlchemy model for A2A task events
+  - `id: Column[String]` - Primary key event identifier
+  - `task_id: Column[String]` - Foreign key to tasks table with CASCADE delete (indexed)
+  - `user_id: Column[String]` - Optional user identifier (indexed)
+  - `created_time: Column[BigInteger]` - Creation timestamp in epoch milliseconds
+  - `topic: Column[Text]` - Event topic
+  - `direction: Column[String]` - Event direction (max 50 chars)
+  - `payload: Column[JSON]` - Event payload as JSON
+  - `task: relationship` - SQLAlchemy relationship to TaskModel
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.models.task_event_model import TaskEventModel
+from sqlalchemy.orm import sessionmaker
+
+# Create a task event
+event = TaskEventModel(
+    id="event_123",
+    task_id="task_456",
+    user_id="user_789",
+    created_time=1640995200000,
+    topic="agent/response",
+    direction="inbound",
+    payload={"message": "Task completed", "status": "success"}
+)
+
+# Add to database
+Session = sessionmaker(bind=engine)
+db_session = Session()
+db_session.add(event)
+db_session.commit()
+```
+
+### task_model.py
+**Purpose:** SQLAlchemy model for managing tasks with event relationships and token usage tracking
+**Import:** `from solace_agent_mesh.gateway.http_sse.repository.models.task_model import TaskModel`
+
+**Classes:**
+- `TaskModel(Base)` - SQLAlchemy model for tasks
+  - `id: Column[String]` - Primary key task identifier
+  - `user_id: Column[String]` - User identifier (indexed)
+  - `start_time: Column[BigInteger]` - Task start timestamp in epoch milliseconds
+  - `end_time: Column[BigInteger]` - Optional task end timestamp
+  - `status: Column[String]` - Optional task status
+  - `initial_request_text: Column[Text]` - Optional initial request text (indexed)
+  - `total_input_tokens: Column[Integer]` - Optional total input tokens used
+  - `total_output_tokens: Column[Integer]` - Optional total output tokens used
+  - `total_cached_input_tokens: Column[Integer]` - Optional total cached input tokens
+  - `token_usage_details: Column[JSON]` - Optional detailed token usage information
+  - `events: relationship` - SQLAlchemy relationship to TaskEventModel with cascade delete
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository.models.task_model import TaskModel
+from sqlalchemy.orm import sessionmaker
+
+# Create a new task with token tracking
+task = TaskModel(
+    id="task_123",
+    user_id="user_456",
+    start_time=1640995200000,
+    status="in_progress",
+    initial_request_text="Please help me with this task",
+    total_input_tokens=150,
+    total_output_tokens=300,
+    total_cached_input_tokens=50,
+    token_usage_details={"model": "gpt-4", "breakdown": {"reasoning": 200, "response": 100}}
+)
+
+# Add to database
+Session = sessionmaker(bind=engine)
+db_session = Session()
+db_session.add(task)
+db_session.commit()
+
+# Access related events
+events = task.events  # Returns list of TaskEventModel instances
+```
+
+# content_hash: 65d43bc49dd561efb9955aae2fc39945567e4302c406eea9718ce797d083646c

solace_agent_mesh/gateway/http_sse/repository/models/project_model.py

@@ -0,0 +1,51 @@
+"""
+SQLAlchemy model for project data.
+"""
+
+from sqlalchemy import Column, String, Boolean, BigInteger, Text
+from sqlalchemy.orm import relationship
+from pydantic import BaseModel
+
+from .base import Base
+
+
+class ProjectModel(Base):
+    """SQLAlchemy model for projects."""
+    
+    __tablename__ = "projects"
+    
+    id = Column(String, primary_key=True)
+    name = Column(String, nullable=False)
+    user_id = Column(String, nullable=False)
+    description = Column(Text, nullable=True)
+    system_prompt = Column(Text, nullable=True)
+    default_agent_id = Column(String, nullable=True)
+    created_at = Column(BigInteger, nullable=False)
+    updated_at = Column(BigInteger, nullable=True)  
+    deleted_at = Column(BigInteger, nullable=True)   
+    deleted_by = Column(String, nullable=True)       
+    
+    # Relationships
+    sessions = relationship("SessionModel", back_populates="project")
+    project_users = relationship("ProjectUserModel", back_populates="project", cascade="all, delete-orphan")
+
+
+class CreateProjectModel(BaseModel):
+    """Pydantic model for creating a project."""
+    id: str
+    name: str
+    user_id: str | None = None
+    description: str | None = None
+    system_prompt: str | None = None
+    default_agent_id: str | None = None
+    created_at: int
+    updated_at: int | None = None
+
+
+class UpdateProjectModel(BaseModel):
+    """Pydantic model for updating a project."""
+    name: str | None = None
+    description: str | None = None
+    system_prompt: str | None = None
+    default_agent_id: str | None = None
+    updated_at: int

solace_agent_mesh/gateway/http_sse/repository/models/project_user_model.py

@@ -0,0 +1,75 @@
+"""
+SQLAlchemy model for project user access (junction table).
+"""
+
+from enum import Enum
+from sqlalchemy import Column, String, BigInteger, ForeignKey, UniqueConstraint, Enum as SQLEnum
+from sqlalchemy.orm import relationship
+from pydantic import BaseModel, field_validator
+from typing import Literal
+
+from .base import Base
+
+
+class ProjectRole(str, Enum):
+    """Valid roles for project users."""
+    OWNER = "owner"
+    EDITOR = "editor"
+    VIEWER = "viewer"
+
+
+class ProjectUserModel(Base):
+    """
+    SQLAlchemy model for project user access.
+    
+    This junction table tracks which users have access to which projects,
+    enabling multi-user collaboration on projects.
+    """
+    
+    __tablename__ = "project_users"
+    
+    id = Column(String, primary_key=True)
+    project_id = Column(String, ForeignKey("projects.id", ondelete="CASCADE"), nullable=False)
+    user_id = Column(String, nullable=False)
+    role = Column(SQLEnum(ProjectRole), nullable=False, default=ProjectRole.VIEWER)
+    added_at = Column(BigInteger, nullable=False)  # Epoch timestamp in milliseconds
+    added_by_user_id = Column(String, nullable=False)  # User who granted access
+    
+    # Ensure a user can only be added once per project
+    __table_args__ = (
+        UniqueConstraint('project_id', 'user_id', name='uq_project_user'),
+    )
+    
+    # Relationships
+    project = relationship("ProjectModel", back_populates="project_users")
+
+
+class CreateProjectUserModel(BaseModel):
+    """Pydantic model for creating a project user access record."""
+    id: str
+    project_id: str
+    user_id: str
+    role: Literal["owner", "editor", "viewer"] = "viewer"
+    added_at: int
+    added_by_user_id: str
+    
+    @field_validator('role')
+    @classmethod
+    def validate_role(cls, v: str) -> str:
+        """Validate that role is one of the allowed values."""
+        if v not in [role.value for role in ProjectRole]:
+            raise ValueError(f"Role must be one of: {', '.join([role.value for role in ProjectRole])}")
+        return v
+
+
+class UpdateProjectUserModel(BaseModel):
+    """Pydantic model for updating a project user access record."""
+    role: Literal["owner", "editor", "viewer"] | None = None
+    
+    @field_validator('role')
+    @classmethod
+    def validate_role(cls, v: str | None) -> str | None:
+        """Validate that role is one of the allowed values."""
+        if v is not None and v not in [role.value for role in ProjectRole]:
+            raise ValueError(f"Role must be one of: {', '.join([role.value for role in ProjectRole])}")
+        return v

solace_agent_mesh/gateway/http_sse/repository/models/prompt_model.py

@@ -0,0 +1,159 @@
+"""
+Prompt SQLAlchemy models for prompt library feature.
+"""
+
+from enum import Enum
+from sqlalchemy import BigInteger, Column, String, Text, Integer, Boolean, ForeignKey, UniqueConstraint, Enum as SQLEnum
+from sqlalchemy.orm import relationship
+
+from ...shared import now_epoch_ms
+from .base import Base
+
+
+class PromptGroupRole(str, Enum):
+    """Valid roles for prompt group users."""
+    OWNER = "owner"
+    EDITOR = "editor"
+    VIEWER = "viewer"
+
+
+class PromptGroupModel(Base):
+    """SQLAlchemy model for prompt groups"""
+    
+    __tablename__ = "prompt_groups"
+    
+    # Primary key - String type (not UUID)
+    id = Column(String, primary_key=True)
+    
+    # Core fields
+    name = Column(String(255), nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    category = Column(String(100), nullable=True, index=True)
+    command = Column(String(50), nullable=True, unique=True, index=True)
+    
+    # Ownership
+    user_id = Column(String, nullable=False, index=True)
+    author_name = Column(String(255), nullable=True)
+    
+    # Production prompt reference
+    production_prompt_id = Column(
+        String, 
+        ForeignKey("prompts.id", ondelete="SET NULL"), 
+        nullable=True
+    )
+    
+    # Sharing (optional - for future enhancement)
+    is_shared = Column(Boolean, default=False, nullable=False)
+    
+    # User preferences
+    is_pinned = Column(Boolean, default=False, nullable=False, index=True)
+    
+    # Timestamps - BigInteger (epoch milliseconds) to match SAM convention
+    created_at = Column(BigInteger, nullable=False, default=now_epoch_ms)
+    updated_at = Column(
+        BigInteger, 
+        nullable=False, 
+        default=now_epoch_ms, 
+        onupdate=now_epoch_ms
+    )
+    
+    # Relationships
+    prompts = relationship(
+        "PromptModel",
+        back_populates="group",
+        foreign_keys="PromptModel.group_id",
+        cascade="all, delete-orphan"
+    )
+    production_prompt = relationship(
+        "PromptModel",
+        foreign_keys=[production_prompt_id],
+        post_update=True
+    )
+    prompt_group_users = relationship(
+        "PromptGroupUserModel",
+        back_populates="prompt_group",
+        cascade="all, delete-orphan"
+    )
+    
+    def __repr__(self):
+        return f"<PromptGroupModel(id={self.id}, name={self.name}, command={self.command})>"
+
+
+class PromptModel(Base):
+    """SQLAlchemy model for individual prompt versions"""
+    
+    __tablename__ = "prompts"
+    
+    # Primary key - String type (not UUID)
+    id = Column(String, primary_key=True)
+    
+    # Content
+    prompt_text = Column(Text, nullable=False)
+    
+    # Versioned metadata fields (copied from group at version creation time)
+    name = Column(String(255), nullable=True)
+    description = Column(Text, nullable=True)
+    category = Column(String(100), nullable=True)
+    command = Column(String(50), nullable=True)
+    
+    # Group relationship
+    group_id = Column(
+        String,
+        ForeignKey("prompt_groups.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True
+    )
+    
+    # Ownership
+    user_id = Column(String, nullable=False, index=True)
+    
+    # Versioning
+    version = Column(Integer, default=1, nullable=False)
+    
+    # Timestamps - BigInteger (epoch milliseconds)
+    created_at = Column(BigInteger, nullable=False, default=now_epoch_ms)
+    updated_at = Column(
+        BigInteger,
+        nullable=False,
+        default=now_epoch_ms,
+        onupdate=now_epoch_ms
+    )
+    
+    # Relationships
+    group = relationship(
+        "PromptGroupModel",
+        back_populates="prompts",
+        foreign_keys=[group_id]
+    )
+    
+    def __repr__(self):
+        return f"<PromptModel(id={self.id}, group_id={self.group_id}, version={self.version})>"
+
+
+class PromptGroupUserModel(Base):
+    """
+    SQLAlchemy model for prompt group user access.
+    
+    This junction table tracks which users have access to which prompt groups,
+    enabling multi-user collaboration on prompts with role-based permissions.
+    """
+    
+    __tablename__ = "prompt_group_users"
+    
+    id = Column(String, primary_key=True)
+    prompt_group_id = Column(String, ForeignKey("prompt_groups.id", ondelete="CASCADE"), nullable=False)
+    user_id = Column(String, nullable=False)
+    role = Column(SQLEnum(PromptGroupRole), nullable=False, default=PromptGroupRole.VIEWER)
+    added_at = Column(BigInteger, nullable=False)  # Epoch timestamp in milliseconds
+    added_by_user_id = Column(String, nullable=False)  # User who granted access
+    
+    # Ensure a user can only be added once per prompt group
+    __table_args__ = (
+        UniqueConstraint('prompt_group_id', 'user_id', name='uq_prompt_group_user'),
+    )
+    
+    # Relationships
+    prompt_group = relationship("PromptGroupModel", back_populates="prompt_group_users")
+    
+    def __repr__(self):
+        return f"<PromptGroupUserModel(id={self.id}, prompt_group_id={self.prompt_group_id}, user_id={self.user_id}, role={self.role})>"

solace_agent_mesh/gateway/http_sse/repository/models/session_model.py

@@ -0,0 +1,53 @@
+"""
+Session SQLAlchemy model and Pydantic models for strongly-typed operations.
+"""
+
+from sqlalchemy import BigInteger, Column, String, ForeignKey
+from pydantic import BaseModel
+from sqlalchemy.orm import relationship
+
+from ...shared import now_epoch_ms
+from .base import Base
+
+
+class SessionModel(Base):
+    """SQLAlchemy model for sessions."""
+
+    __tablename__ = "sessions"
+
+    id = Column(String, primary_key=True)
+    name = Column(String, nullable=True)
+    user_id = Column(String, nullable=False)
+    agent_id = Column(String, nullable=True)
+    project_id = Column(String, ForeignKey("projects.id"), nullable=True)
+    created_time = Column(BigInteger, nullable=False, default=now_epoch_ms)
+    updated_time = Column(
+        BigInteger, nullable=False, default=now_epoch_ms, onupdate=now_epoch_ms
+    )
+    deleted_at = Column(BigInteger, nullable=True)
+    deleted_by = Column(String, nullable=True)
+
+    # Relationship to chat tasks
+    chat_tasks = relationship(
+        "ChatTaskModel", back_populates="session", cascade="all, delete-orphan"
+    )
+    project = relationship("ProjectModel", back_populates="sessions")
+
+
+class CreateSessionModel(BaseModel):
+    """Pydantic model for creating a session."""
+    id: str
+    name: str | None
+    user_id: str
+    agent_id: str | None
+    project_id: str | None = None
+    created_time: int
+    updated_time: int
+
+
+class UpdateSessionModel(BaseModel):
+    """Pydantic model for updating a session."""
+    name: str | None = None
+    agent_id: str | None = None
+    project_id: str | None = None
+    updated_time: int

solace_agent_mesh/gateway/http_sse/repository/models/task_event_model.py

@@ -0,0 +1,25 @@
+"""
+Task Event SQLAlchemy model.
+"""
+
+from sqlalchemy import JSON, BigInteger, Column, ForeignKey, String, Text
+from sqlalchemy.orm import relationship
+
+from .base import Base
+
+
+class TaskEventModel(Base):
+    """SQLAlchemy model for A2A task events."""
+
+    __tablename__ = "task_events"
+
+    id = Column(String, primary_key=True)
+    task_id = Column(String, ForeignKey("tasks.id", ondelete="CASCADE"), index=True)
+    user_id = Column(String, nullable=True, index=True)
+    created_time = Column(BigInteger, nullable=False)
+    topic = Column(Text, nullable=False)
+    direction = Column(String(50), nullable=False)
+    payload = Column(JSON, nullable=False)
+
+    # Relationship to task
+    task = relationship("TaskModel", back_populates="events")

solace_agent_mesh/gateway/http_sse/repository/models/task_model.py

@@ -0,0 +1,39 @@
+"""
+Task SQLAlchemy model.
+"""
+
+from sqlalchemy import BigInteger, Boolean, Column, Integer, JSON, String, Text
+from sqlalchemy.orm import relationship
+
+from .base import Base
+
+
+class TaskModel(Base):
+    """SQLAlchemy model for tasks."""
+
+    __tablename__ = "tasks"
+
+    id = Column(String, primary_key=True)
+    user_id = Column(String, nullable=False, index=True)
+    parent_task_id = Column(String, nullable=True, index=True)
+    start_time = Column(BigInteger, nullable=False)
+    end_time = Column(BigInteger, nullable=True)
+    status = Column(String, nullable=True)
+    initial_request_text = Column(Text, nullable=True, index=True)
+    
+    # Token usage columns
+    total_input_tokens = Column(Integer, nullable=True)
+    total_output_tokens = Column(Integer, nullable=True)
+    total_cached_input_tokens = Column(Integer, nullable=True)
+    token_usage_details = Column(JSON, nullable=True)
+    
+    # Background task execution columns
+    execution_mode = Column(String(20), nullable=True, default="foreground", index=True)
+    last_activity_time = Column(BigInteger, nullable=True, index=True)
+    background_execution_enabled = Column(Boolean, nullable=True, default=False)
+    max_execution_time_ms = Column(BigInteger, nullable=True)
+
+    # Relationship to events
+    events = relationship(
+        "TaskEventModel", back_populates="task", cascade="all, delete-orphan"
+    )