remdb 0.2.6__py3-none-any.whl → 0.3.118__py3-none-any.whl

rem/models/entities/feedback.py

@@ -0,0 +1,123 @@
+"""
+Feedback - User feedback on chat messages and sessions.
+
+Feedback allows users to rate and categorize responses, providing
+data for evaluation and model improvement. Feedback can be attached
+to specific messages or entire sessions.
+
+Trace Integration:
+- Feedback references trace_id/span_id for OTEL/Phoenix integration
+- Can attach annotations to Phoenix spans for unified observability
+
+Predefined Categories (system-defined, extensible):
+- INCOMPLETE: Response lacks expected information
+- INACCURATE: Response contains factual errors
+- POOR_TONE: Inappropriate or unprofessional tone
+- OFF_TOPIC: Response doesn't address the question
+- TOO_VERBOSE: Unnecessarily long response
+- TOO_BRIEF: Insufficiently detailed response
+- HELPFUL: Positive feedback marker
+- EXCELLENT: Exceptionally good response
+"""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import Field
+
+from ..core import CoreModel
+
+
+class FeedbackCategory(str, Enum):
+    """Predefined feedback categories (system-defined)."""
+
+    # Negative categories
+    INCOMPLETE = "incomplete"
+    INACCURATE = "inaccurate"
+    POOR_TONE = "poor_tone"
+    OFF_TOPIC = "off_topic"
+    TOO_VERBOSE = "too_verbose"
+    TOO_BRIEF = "too_brief"
+    CONFUSING = "confusing"
+    UNSAFE = "unsafe"
+
+    # Positive categories
+    HELPFUL = "helpful"
+    EXCELLENT = "excellent"
+    ACCURATE = "accurate"
+    WELL_WRITTEN = "well_written"
+
+    # Neutral/Other
+    OTHER = "other"
+
+
+class Feedback(CoreModel):
+    """
+    User feedback on a message or session.
+
+    Captures structured feedback including:
+    - Rating (1-5 scale or thumbs up/down)
+    - Categories (predefined or custom)
+    - Free-text comment
+    - Trace reference for OTEL/Phoenix integration
+
+    The feedback can be attached to:
+    - A specific message (message_id set)
+    - An entire session (session_id set, message_id null)
+    """
+
+    # Target reference (at least one required)
+    session_id: str = Field(
+        ...,
+        description="Session ID this feedback relates to",
+    )
+    message_id: str | None = Field(
+        default=None,
+        description="Specific message ID (null for session-level feedback)",
+    )
+
+    # Rating (flexible: 1-5, or -1/1 for thumbs)
+    rating: int | None = Field(
+        default=None,
+        ge=-1,
+        le=5,
+        description="Rating: -1 (thumbs down), 1 (thumbs up), or 1-5 scale",
+    )
+
+    # Categories (can select multiple)
+    categories: list[str] = Field(
+        default_factory=list,
+        description="Selected feedback categories (from FeedbackCategory or custom)",
+    )
+
+    # Free-text comment
+    comment: str | None = Field(
+        default=None,
+        description="Optional free-text feedback comment",
+    )
+
+    # Trace reference for OTEL/Phoenix integration
+    trace_id: str | None = Field(
+        default=None,
+        description="OTEL trace ID for linking to observability",
+    )
+    span_id: str | None = Field(
+        default=None,
+        description="OTEL span ID for specific span feedback",
+    )
+
+    # Phoenix annotation status
+    phoenix_synced: bool = Field(
+        default=False,
+        description="Whether feedback has been synced to Phoenix as annotation",
+    )
+    phoenix_annotation_id: str | None = Field(
+        default=None,
+        description="Phoenix annotation ID after sync",
+    )
+
+    # Annotator info
+    annotator_kind: str = Field(
+        default="HUMAN",
+        description="Annotator type: HUMAN, LLM, CODE",
+    )

rem/models/entities/message.py

@@ -6,6 +6,11 @@ that can be grouped into conversations or moments.
 
 Messages are simpler than Resources but share the same graph connectivity
 through CoreModel inheritance.
+
+Trace Integration:
+- trace_id: OTEL trace ID for linking to observability
+- span_id: OTEL span ID for specific span reference
+- These enable feedback to be attached to Phoenix annotations
 """
 
 from pydantic import Field
@@ -19,6 +24,9 @@ class Message(CoreModel):
 
     Represents individual messages in conversations, chats, or other
     communication contexts. Tenant isolation is provided via CoreModel.tenant_id field.
+
+    Trace fields (trace_id, span_id) enable integration with OTEL/Phoenix
+    for observability and feedback annotation.
     """
 
     content: str = Field(
@@ -27,9 +35,30 @@ class Message(CoreModel):
     )
     message_type: str | None = Field(
         default=None,
-        description="Message type e.g role",
+        description="Message type e.g. role: 'user', 'assistant', 'system', 'tool'",
     )
     session_id: str | None = Field(
         default=None,
         description="Session identifier for tracking message context",
     )
+    prompt: str | None = Field(
+        default=None,
+        description="Custom prompt used for this message (if overridden from default)",
+    )
+    model: str | None = Field(
+        default=None,
+        description="Model used for generating this message (provider:model format)",
+    )
+    token_count: int | None = Field(
+        default=None,
+        description="Token count for this message",
+    )
+    # OTEL/Phoenix trace integration
+    trace_id: str | None = Field(
+        default=None,
+        description="OTEL trace ID for observability integration",
+    )
+    span_id: str | None = Field(
+        default=None,
+        description="OTEL span ID for specific span reference",
+    )

rem/models/entities/session.py

@@ -0,0 +1,83 @@
+"""
+Session - Conversation sessions in REM.
+
+Sessions group related messages together and can have different modes:
+- normal: Standard conversation session
+- evaluation: For LLM evaluation, stores original trace and overridden settings
+
+Sessions allow overriding settings like model, temperature, and custom prompts
+for evaluation and experimentation purposes.
+"""
+
+from enum import Enum
+
+from pydantic import Field
+
+from ..core import CoreModel
+
+
+class SessionMode(str, Enum):
+    """Session mode types."""
+
+    NORMAL = "normal"
+    EVALUATION = "evaluation"
+
+
+class Session(CoreModel):
+    """
+    Conversation session container.
+
+    Groups messages together and supports different modes for normal conversations
+    and evaluation/experimentation scenarios.
+
+    For evaluation sessions, stores:
+    - original_trace_id: Reference to the original session being evaluated
+    - settings_overrides: Model, temperature, prompt overrides
+    - prompt: Custom prompt being tested
+
+    Default sessions are lightweight - just a session_id on messages.
+    Special sessions store additional metadata for experiments.
+    """
+
+    name: str = Field(
+        ...,
+        description="Session name/identifier",
+        json_schema_extra={"entity_key": True},
+    )
+    mode: SessionMode = Field(
+        default=SessionMode.NORMAL,
+        description="Session mode: 'normal' or 'evaluation'",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional session description",
+    )
+    # Evaluation-specific fields
+    original_trace_id: str | None = Field(
+        default=None,
+        description="For evaluation mode: ID of the original session/trace being evaluated",
+    )
+    settings_overrides: dict | None = Field(
+        default=None,
+        description="Settings overrides (model, temperature, max_tokens, system_prompt)",
+    )
+    prompt: str | None = Field(
+        default=None,
+        description="Custom prompt for this session (can override agent prompt)",
+    )
+    # Agent context
+    agent_schema_uri: str | None = Field(
+        default=None,
+        description="Agent schema used for this session",
+    )
+    # Summary stats (updated as session progresses)
+    message_count: int = Field(
+        default=0,
+        description="Number of messages in this session",
+    )
+    total_tokens: int | None = Field(
+        default=None,
+        description="Total tokens used in this session",
+    )
+
+    model_config = {"use_enum_values": True}

rem/models/entities/shared_session.py

@@ -0,0 +1,180 @@
+"""
+SharedSession - Session sharing between users in REM.
+
+SharedSessions enable collaborative access to conversation sessions. When a user
+shares a session with another user, a SharedSession record is created to track
+this relationship.
+
+## Design Philosophy
+
+Messages already have a session_id field that links them to sessions. The Session
+entity itself is optional and can be left-joined - we don't require explicit Session
+records for sharing to work. What matters is the session_id on messages.
+
+SharedSession is a lightweight linking table that:
+1. Records who shared which session with whom
+2. Enables soft deletion (deleted_at) so shares can be revoked without data loss
+3. Supports aggregation queries to see "who is sharing with me"
+
+## Data Model
+
+    SharedSession
+    ├── session_id: str          # The session being shared (matches Message.session_id)
+    ├── owner_user_id: str       # Who owns/created the session (the sharer)
+    ├── shared_with_user_id: str # Who the session is shared with (the recipient)
+    ├── tenant_id: str           # Multi-tenancy isolation
+    ├── created_at: datetime     # When the share was created
+    ├── updated_at: datetime     # Last modification
+    └── deleted_at: datetime     # Soft delete (null = active share)
+
+## Aggregation Query
+
+The primary use case is answering: "Who is sharing messages with me?"
+
+This is provided by a Postgres function that aggregates:
+- Messages grouped by owner_user_id
+- Joined with users table for name/email
+- Counting messages with min/max dates
+- Filtering out deleted shares
+
+Result shape:
+    {
+        "user_id": "uuid",
+        "name": "John Doe",
+        "email": "john@example.com",
+        "message_count": 42,
+        "first_message_at": "2024-01-15T10:30:00Z",
+        "last_message_at": "2024-03-20T14:45:00Z",
+        "session_count": 3
+    }
+
+## API Endpoints
+
+1. POST /api/v1/sessions/{session_id}/share
+   - Share a session with another user
+   - Body: { "shared_with_user_id": "..." }
+   - Creates SharedSession record
+
+2. DELETE /api/v1/sessions/{session_id}/share/{shared_with_user_id}
+   - Revoke a share (soft delete)
+   - Sets deleted_at on SharedSession
+
+3. GET /api/v1/shared-with-me
+   - Get paginated aggregate of users sharing with you
+   - Query params: page, page_size (default 50)
+   - Returns: list of user summaries with message counts
+
+4. GET /api/v1/shared-with-me/{user_id}/messages
+   - Get messages from a specific user's shared sessions
+   - Uses existing session message loading
+   - Respects pagination
+
+## Soft Delete Pattern
+
+Removing a share does NOT delete the SharedSession record. Instead:
+- deleted_at is set to current timestamp
+- All queries filter WHERE deleted_at IS NULL
+- This preserves audit trail and allows "undo"
+
+To permanently delete, an admin can run:
+    DELETE FROM shared_sessions WHERE deleted_at IS NOT NULL AND deleted_at < NOW() - INTERVAL '30 days'
+
+## Example Usage
+
+    # Share a session
+    POST /api/v1/sessions/abc-123/share
+    {"shared_with_user_id": "user-456"}
+
+    # See who's sharing with me
+    GET /api/v1/shared-with-me
+    {
+        "data": [
+            {
+                "user_id": "user-789",
+                "name": "Alice",
+                "email": "alice@example.com",
+                "message_count": 150,
+                "session_count": 5,
+                "first_message_at": "2024-01-01T00:00:00Z",
+                "last_message_at": "2024-03-15T12:00:00Z"
+            }
+        ],
+        "metadata": {"total": 1, "page": 1, "page_size": 50, ...}
+    }
+
+    # Get messages from Alice's shared sessions
+    GET /api/v1/shared-with-me/user-789/messages?page=1&page_size=50
+
+    # Revoke a share
+    DELETE /api/v1/sessions/abc-123/share/user-456
+"""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from ..core import CoreModel
+
+
+class SharedSession(CoreModel):
+    """
+    Session sharing record between users.
+
+    Links a session (identified by session_id from Message records) to a
+    recipient user, enabling collaborative access to conversation history.
+    """
+
+    session_id: str = Field(
+        ...,
+        description="The session being shared (matches Message.session_id)",
+    )
+    owner_user_id: str = Field(
+        ...,
+        description="User ID of the session owner (the sharer)",
+    )
+    shared_with_user_id: str = Field(
+        ...,
+        description="User ID of the recipient (who can now view the session)",
+    )
+
+
+class SharedSessionCreate(BaseModel):
+    """Request to create a session share."""
+
+    shared_with_user_id: str = Field(
+        ...,
+        description="User ID to share the session with",
+    )
+
+
+class SharedWithMeSummary(BaseModel):
+    """
+    Aggregate summary of a user sharing sessions with you.
+
+    Returned by GET /api/v1/shared-with-me endpoint.
+    """
+
+    user_id: str = Field(description="User ID of the person sharing with you")
+    name: Optional[str] = Field(default=None, description="User's display name")
+    email: Optional[str] = Field(default=None, description="User's email address")
+    message_count: int = Field(description="Total messages across all shared sessions")
+    session_count: int = Field(description="Number of sessions shared with you")
+    first_message_at: Optional[datetime] = Field(
+        default=None,
+        description="Timestamp of earliest message in shared sessions",
+    )
+    last_message_at: Optional[datetime] = Field(
+        default=None,
+        description="Timestamp of most recent message in shared sessions",
+    )
+
+
+class SharedWithMeResponse(BaseModel):
+    """Response for paginated shared-with-me query."""
+
+    object: str = "list"
+    data: list[SharedWithMeSummary] = Field(
+        description="List of users sharing sessions with you"
+    )
+    metadata: dict = Field(description="Pagination metadata")

rem/models/entities/user.py

@@ -22,9 +22,12 @@ from ..core import CoreModel
 class UserTier(str, Enum):
     """User subscription tier for feature gating."""
 
+    ANONYMOUS = "anonymous"
     FREE = "free"
-    SILVER = "silver"
-    GOLD = "gold"
+    BASIC = "basic"
+    PRO = "pro"
+    SILVER = "silver"  # Deprecated? Keeping for backward compatibility if needed
+    GOLD = "gold"      # Deprecated? Keeping for backward compatibility if needed
 
 
 class User(CoreModel):
@@ -57,7 +60,11 @@ class User(CoreModel):
     )
     tier: UserTier = Field(
         default=UserTier.FREE,
-        description="User subscription tier (free, silver, gold) for feature gating",
+        description="User subscription tier (free, basic, pro) for feature gating",
+    )
+    anonymous_ids: list[str] = Field(
+        default_factory=list,
+        description="Linked anonymous session IDs used for merging history",
     )
     sec_policy: dict = Field(
         default_factory=dict,