remdb 0.3.14__py3-none-any.whl → 0.3.157__py3-none-any.whl

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/subscriber.py

@@ -0,0 +1,175 @@
+"""
+Subscriber - Email subscription management.
+
+This model stores subscribers who sign up via websites/apps.
+Subscribers can be collected before user registration for newsletters,
+updates, and approval-based access control.
+
+Key features:
+- Deterministic UUID from email (same email = same ID)
+- Approval workflow for access control
+- Tags for segmentation
+- Origin tracking for analytics
+"""
+
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+
+from pydantic import Field, EmailStr, model_validator
+
+from ..core import CoreModel
+
+
+class SubscriberStatus(str, Enum):
+    """Subscription status."""
+
+    ACTIVE = "active"           # Actively subscribed
+    UNSUBSCRIBED = "unsubscribed"  # User unsubscribed
+    BOUNCED = "bounced"         # Email bounced
+    PENDING = "pending"         # Pending confirmation (if double opt-in)
+
+
+class SubscriberOrigin(str, Enum):
+    """Where the subscription originated from."""
+
+    WEBSITE = "website"         # Main website subscribe form
+    LANDING_PAGE = "landing_page"  # Campaign landing page
+    APP = "app"                 # In-app subscription
+    IMPORT = "import"           # Bulk import
+    REFERRAL = "referral"       # Referred by another user
+    OTHER = "other"
+
+
+class Subscriber(CoreModel):
+    """
+    Email subscriber for newsletters and access control.
+
+    This model captures subscribers who sign up via the website, landing pages,
+    or in-app prompts. Uses deterministic UUID from email for natural upserts.
+
+    Access control via `approved` field:
+    - When email auth checks subscriber status, only approved subscribers
+      can complete login (if approval is enabled in settings).
+    - Subscribers can be pre-approved, or approved manually/automatically.
+
+    Usage:
+        from rem.services.postgres import Repository
+        from rem.models.entities import Subscriber, SubscriberStatus
+
+        repo = Repository(Subscriber, db=db)
+
+        # Create subscriber (ID auto-generated from email)
+        subscriber = Subscriber(
+            email="user@example.com",
+            name="John Doe",
+            origin=SubscriberOrigin.WEBSITE,
+        )
+        await repo.upsert(subscriber)
+
+        # Check if approved for login
+        subscriber = await repo.get_by_id(subscriber.id, tenant_id="default")
+        if subscriber and subscriber.approved:
+            # Allow login
+            pass
+    """
+
+    # Required field
+    email: EmailStr = Field(
+        description="Subscriber's email address (unique identifier)"
+    )
+
+    # Optional fields
+    name: Optional[str] = Field(
+        default=None,
+        description="Subscriber's name (optional)"
+    )
+
+    comment: Optional[str] = Field(
+        default=None,
+        max_length=500,
+        description="Optional comment or message from subscriber"
+    )
+
+    status: SubscriberStatus = Field(
+        default=SubscriberStatus.ACTIVE,
+        description="Current subscription status"
+    )
+
+    # Access control
+    approved: bool = Field(
+        default=False,
+        description="Whether subscriber is approved for login (for approval workflows)"
+    )
+
+    approved_at: Optional[datetime] = Field(
+        default=None,
+        description="When the subscriber was approved"
+    )
+
+    approved_by: Optional[str] = Field(
+        default=None,
+        description="Who approved the subscriber (user ID or 'system')"
+    )
+
+    # Origin tracking
+    origin: SubscriberOrigin = Field(
+        default=SubscriberOrigin.WEBSITE,
+        description="Where the subscription originated"
+    )
+
+    origin_detail: Optional[str] = Field(
+        default=None,
+        description="Additional origin context (e.g., campaign name, page URL)"
+    )
+
+    # Timestamps
+    subscribed_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When the subscription was created"
+    )
+
+    unsubscribed_at: Optional[datetime] = Field(
+        default=None,
+        description="When the user unsubscribed (if applicable)"
+    )
+
+    # Compliance
+    ip_address: Optional[str] = Field(
+        default=None,
+        description="IP address at subscription time (for compliance)"
+    )
+
+    user_agent: Optional[str] = Field(
+        default=None,
+        description="Browser user agent at subscription time"
+    )
+
+    # Segmentation
+    tags: list[str] = Field(
+        default_factory=list,
+        description="Tags for segmentation (e.g., ['early-access', 'beta'])"
+    )
+
+    @staticmethod
+    def email_to_uuid(email: str) -> uuid.UUID:
+        """Generate a deterministic UUID from an email address.
+
+        Uses UUID v5 with DNS namespace for consistency with
+        EmailService.generate_user_id_from_email().
+
+        Args:
+            email: Email address
+
+        Returns:
+            Deterministic UUID
+        """
+        return uuid.uuid5(uuid.NAMESPACE_DNS, email.lower().strip())
+
+    @model_validator(mode="after")
+    def set_id_from_email(self) -> "Subscriber":
+        """Auto-generate deterministic ID from email for natural upsert."""
+        if self.email:
+            self.id = self.email_to_uuid(self.email)
+        return self

rem/models/entities/user.py

@@ -22,6 +22,7 @@ from ..core import CoreModel
 class UserTier(str, Enum):
     """User subscription tier for feature gating."""
 
+    BLOCKED = "blocked"  # User is blocked from logging in
     ANONYMOUS = "anonymous"
     FREE = "free"
     BASIC = "basic"

rem/registry.py

@@ -123,6 +123,7 @@ class ModelRegistry:
             return
 
         from .models.entities import (
+            Feedback,
             File,
             ImageResource,
             Message,
@@ -131,19 +132,24 @@ class ModelRegistry:
             OntologyConfig,
             Resource,
             Schema,
+            Session,
+            SharedSession,
             User,
         )
 
         core_models = [
-            Resource,
+            Feedback,
+            File,
             ImageResource,
             Message,
-            User,
-            File,
             Moment,
-            Schema,
             Ontology,
             OntologyConfig,
+            Resource,
+            Schema,
+            Session,
+            SharedSession,
+            User,
         ]
 
         for model in core_models:

rem/schemas/agents/core/agent-builder.yaml

@@ -0,0 +1,134 @@
+type: object
+description: |
+  # Agent Builder - Create Custom AI Agents Through Conversation
+
+  You help users create custom AI agents by chatting with them naturally.
+  Gather requirements conversationally, show previews, and save the agent when ready.
+
+  ## Your Workflow
+
+  1. **Understand the need**: Ask what they want the agent to do
+  2. **Define personality**: Help them choose tone and style
+  3. **Structure outputs**: If needed, define what data the agent captures
+  4. **Preview**: Show them what the agent will look like
+  5. **Save**: Use `save_agent` tool to persist it
+
+  ## Conversation Style
+
+  Be friendly and helpful. Ask one or two questions at a time.
+  Don't overwhelm with options - guide them step by step.
+
+  ## Gathering Requirements
+
+  Ask about:
+  - What should this agent help with?
+  - What tone should it have? (casual, professional, empathetic, etc.)
+  - Should it capture any specific information? (optional)
+  - What should it be called?
+
+  ## Preview Format
+
+  Before saving, show a preview using markdown:
+
+  ```
+  ## Agent Preview: {name}
+
+  **Personality:**
+  {brief description of tone and approach}
+
+  **System Prompt:**
+  {the actual prompt that will guide the agent}
+
+  **Structured Fields:** (if any)
+  | Field | Type | Description |
+  |-------|------|-------------|
+  | answer | string | Response to user |
+  | ... | ... | ... |
+  ```
+
+  Ask: "Does this look good? I can save it now or we can adjust anything."
+
+  ## Saving the Agent
+
+  When the user approves, call `save_agent` with:
+  - `name`: kebab-case name (e.g., "customer-support-bot")
+  - `description`: The full system prompt
+  - `properties`: Structured output fields (optional, defaults to just "answer")
+  - `required`: Which fields are required (optional, defaults to ["answer"])
+  - `tags`: Relevant tags for organization
+
+  ## Default Tools
+
+  All agents automatically get `search_rem` and `register_metadata` tools.
+  You don't need to specify these.
+
+  ## Example Conversation
+
+  User: "I want an agent that helps write professional emails"
+
+  You: "Great idea! Let me help you create an email writing assistant.
+
+  What tone should it have? For example:
+  - Professional and formal
+  - Friendly but polished
+  - Direct and concise"
+
+  User: "Friendly but polished"
+
+  You: "Perfect! Should it just write emails, or also help with things like:
+  - Suggesting subject lines
+  - Adjusting tone for different recipients
+  - Summarizing long email threads"
+
+  User: "All of those would be helpful"
+
+  You: "Let me show you a preview:
+
+  ## Agent Preview: email-assistant
+
+  **Personality:** Friendly, professional, helpful writing partner
+
+  **System Prompt:**
+  You are a friendly email writing assistant. Help users craft polished,
+  professional emails while maintaining a warm tone. You can:
+  - Write new emails from scratch
+  - Suggest compelling subject lines
+  - Adjust tone for different audiences
+  - Summarize long email threads
+
+  Always ask clarifying questions if the request is unclear.
+
+  **Structured Fields:**
+  | Field | Type | Description |
+  |-------|------|-------------|
+  | answer | string | Your response or the drafted email |
+
+  Does this look good? I can save it now or adjust anything."
+
+  User: "Looks great, save it!"
+
+  You: *calls save_agent tool*
+  "Done! Your email-assistant is ready. Use `/custom-agent email-assistant` to start chatting with it."
+
+properties:
+  answer:
+    type: string
+    description: Your conversational response to the user
+
+required:
+  - answer
+
+json_schema_extra:
+  kind: agent
+  name: agent-builder
+  version: "1.0.0"
+  tags:
+    - meta
+    - builder
+  tools:
+    - name: save_agent
+      description: "Save the agent schema to make it available for use"
+    - name: search_rem
+      description: "Search for existing agents as examples"
+    - name: register_metadata
+      description: "Record session metadata"

rem/schemas/agents/examples/contract-analyzer.yaml

@@ -308,7 +308,7 @@ json_schema_extra:
   - provider_name: anthropic
     model_name: claude-sonnet-4-5-20250929
   - provider_name: openai
-    model_name: gpt-4o
+    model_name: gpt-4.1
   embedding_fields:
   - contract_title
   - contract_type

rem/schemas/agents/examples/contract-extractor.yaml

@@ -131,4 +131,4 @@ json_schema_extra:
   - provider_name: anthropic
     model_name: claude-sonnet-4-5-20250929
   - provider_name: openai
-    model_name: gpt-4o
+    model_name: gpt-4.1

rem/schemas/agents/examples/cv-parser.yaml

@@ -255,7 +255,7 @@ json_schema_extra:
     - provider_name: anthropic
       model_name: claude-sonnet-4-5-20250929
     - provider_name: openai
-      model_name: gpt-4o
+      model_name: gpt-4.1
   embedding_fields:
     - candidate_name
     - professional_summary

rem/schemas/agents/rem.yaml

@@ -63,9 +63,8 @@ description: "# REM Agent - Resources Entities Moments Expert\n\nYou are the REM
   \ disabled, OTEL disabled for local dev)\n- Global settings singleton\n\n## Response\
   \ Guidelines\n\n- Provide clear, concise answers with code examples when helpful\n\
   - Reference specific design patterns from CLAUDE.md when applicable\n- Suggest best\
-  \ practices for cloud-native deployment\n- Include confidence scores based on query\
-  \ clarity and information completeness\n- If uncertain, say so and suggest where\
-  \ to find more information\n\n## Example Queries You Can Answer\n\n- \"How do I\
+  \ practices for cloud-native deployment\n- If uncertain, say so and suggest where\
+  \ to find more information\n\n## Metadata Registration\n\nBefore generating your final response, call the `register_metadata` tool to provide confidence scores and source attribution.\n\n## Example Queries You Can Answer\n\n- \"How do I\
   \ create a new REM entity?\"\n- \"What's the difference between LOOKUP and TRAVERSE\
   \ queries?\"\n- \"How do I add MCP tools to my agent schema?\"\n- \"Explain the\
   \ graph edge pattern in REM\"\n- \"How do I enable OTEL tracing for my agents?\"\
@@ -101,6 +100,9 @@ json_schema_extra:
   kind: agent
   name: rem
   version: 1.0.0
+  # Disable structured output - properties become prompt guidance instead of JSON schema
+  # This enables natural language streaming while still informing the agent about expected elements
+  structured_output: false
   # MCP server configuration for dynamic tool loading (in-process, no subprocess)
   mcp_servers:
     - type: local
@@ -117,6 +119,8 @@ json_schema_extra:
       description: Ingest files into REM creating searchable resources and embeddings
     - name: read_resource
       description: Read MCP resources by URI (schemas, system status, etc.)
+    - name: register_metadata
+      description: Register response metadata (confidence, sources, references) to be emitted as SSE MetadataEvent. Call BEFORE generating final response.
 
   # Explicit resource declarations for reference data
   resources:

rem/services/__init__.py

@@ -4,13 +4,15 @@ REM Services
 Service layer for REM system operations:
 - PostgresService: PostgreSQL/CloudNativePG database operations
 - RemService: REM query execution and graph operations
+- EmailService: Transactional emails and passwordless login
 
 For file/S3 operations, use rem.services.fs instead:
     from rem.services.fs import FS, S3Provider
 """
 
+from .email import EmailService
 from .fs.service import FileSystemService
 from .postgres import PostgresService
 from .rem import RemService
 
-__all__ = ["PostgresService", "RemService", "FileSystemService"]
+__all__ = ["EmailService", "PostgresService", "RemService", "FileSystemService"]