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

rem/models/entities/shared_session.py

@@ -0,0 +1,206 @@
+"""
+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 uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from ...utils.date_utils import utc_now
+
+
+class SharedSession(BaseModel):
+    """
+    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.
+
+    This is NOT a CoreModel - it's a lightweight linking table without
+    graph edges, metadata, or embeddings.
+    """
+
+    id: Optional[UUID] = Field(
+        default=None,
+        description="Unique identifier (auto-generated)",
+    )
+    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)",
+    )
+    tenant_id: str = Field(
+        default="default",
+        description="Tenant identifier for multi-tenancy isolation",
+    )
+    created_at: datetime = Field(
+        default_factory=utc_now,
+        description="When the share was created",
+    )
+    updated_at: datetime = Field(
+        default_factory=utc_now,
+        description="Last modification timestamp",
+    )
+    deleted_at: Optional[datetime] = Field(
+        default=None,
+        description="Soft delete timestamp (null = active share)",
+    )
+
+    model_config = {"from_attributes": True}
+
+
+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,

rem/registry.py

@@ -0,0 +1,367 @@
+"""
+REM Extension Registry - Register custom models and schema paths.
+
+This module provides registration for downstream applications extending REM:
+1. Models - for database schema generation
+2. Schema paths - for agent/evaluator schema discovery
+
+Usage:
+    import rem
+    from rem.models.core import CoreModel
+
+    # Register custom models
+    @rem.register_model
+    class CustomEntity(CoreModel):
+        name: str
+        custom_field: str
+
+    # Or register multiple at once
+    rem.register_models(ModelA, ModelB, ModelC)
+
+    # Register schema search paths
+    rem.register_schema_path("/app/custom-agents")
+    rem.register_schema_paths("/app/agents", "/app/evaluators")
+
+    # Then:
+    # - Schema generation includes your models: rem db schema generate
+    # - Schema loading finds your custom agents: load_agent_schema("my-agent")
+"""
+
+from dataclasses import dataclass
+from typing import Callable
+
+from loguru import logger
+from pydantic import BaseModel
+
+
+@dataclass
+class ModelExtension:
+    """Container for Pydantic model extension."""
+
+    model: type[BaseModel]
+    table_name: str | None = None  # Optional: override inferred table name
+    entity_key_field: str | None = None  # Optional: override inferred entity key
+
+
+class ModelRegistry:
+    """
+    Registry for Pydantic models used in schema generation.
+
+    Models registered here are discovered by SchemaGenerator alongside
+    REM's core models.
+    """
+
+    def __init__(self) -> None:
+        self._models: dict[str, ModelExtension] = {}
+        self._core_models_registered: bool = False
+
+    def clear(self) -> None:
+        """Clear all registered models. Useful for testing."""
+        self._models.clear()
+        self._core_models_registered = False
+        logger.debug("Model registry cleared")
+
+    def register(
+        self,
+        model: type[BaseModel],
+        table_name: str | None = None,
+        entity_key_field: str | None = None,
+    ) -> type[BaseModel]:
+        """
+        Register a Pydantic model for database schema generation.
+
+        Args:
+            model: Pydantic model class (should inherit from CoreModel)
+            table_name: Optional table name override (inferred from class name if not provided)
+            entity_key_field: Optional entity key field override (inferred if not provided)
+
+        Returns:
+            The model class (allows use as decorator)
+
+        Example:
+            import rem
+            from rem.models.core import CoreModel
+
+            @rem.register_model
+            class CustomEntity(CoreModel):
+                name: str
+                custom_field: str
+
+            # Or with options:
+            rem.register_model(CustomEntity, table_name="custom_entities")
+        """
+        model_name = model.__name__
+        if model_name in self._models:
+            logger.warning(f"Model {model_name} already registered, overwriting")
+
+        self._models[model_name] = ModelExtension(
+            model=model,
+            table_name=table_name,
+            entity_key_field=entity_key_field,
+        )
+        logger.debug(f"Registered model: {model_name}")
+        return model
+
+    def register_many(self, *models: type[BaseModel]) -> None:
+        """
+        Register multiple models at once.
+
+        Example:
+            import rem
+            rem.register_models(ModelA, ModelB, ModelC)
+        """
+        for model in models:
+            self.register(model)
+
+    def register_core_models(self) -> None:
+        """
+        Register REM's built-in core models.
+
+        Called automatically by schema generator if not already done.
+        """
+        if self._core_models_registered:
+            return
+
+        from .models.entities import (
+            File,
+            ImageResource,
+            Message,
+            Moment,
+            Ontology,
+            OntologyConfig,
+            Resource,
+            Schema,
+            User,
+        )
+
+        core_models = [
+            Resource,
+            ImageResource,
+            Message,
+            User,
+            File,
+            Moment,
+            Schema,
+            Ontology,
+            OntologyConfig,
+        ]
+
+        for model in core_models:
+            if model.__name__ not in self._models:
+                self.register(model)
+
+        self._core_models_registered = True
+        logger.debug(f"Registered {len(core_models)} core models")
+
+    def get_models(self, include_core: bool = True) -> dict[str, ModelExtension]:
+        """
+        Get all registered models.
+
+        Args:
+            include_core: If True, ensures core models are registered first
+
+        Returns:
+            Dict mapping model name to ModelExtension
+        """
+        if include_core:
+            self.register_core_models()
+        return self._models.copy()
+
+    def get_model_classes(self, include_core: bool = True) -> dict[str, type[BaseModel]]:
+        """
+        Get all registered model classes (without extension metadata).
+
+        Args:
+            include_core: If True, ensures core models are registered first
+
+        Returns:
+            Dict mapping model name to model class
+        """
+        models = self.get_models(include_core)
+        return {name: ext.model for name, ext in models.items()}
+
+
+# =============================================================================
+# SCHEMA PATH REGISTRY
+# =============================================================================
+
+
+class SchemaPathRegistry:
+    """
+    Registry for custom schema search paths.
+
+    Paths registered here are searched BEFORE built-in package schemas
+    when loading agent/evaluator schemas.
+
+    Search order:
+    1. Exact path (if file exists)
+    2. Paths from this registry (in registration order)
+    3. Paths from SCHEMA__PATHS env var
+    4. Built-in package schemas
+    5. Database LOOKUP
+    """
+
+    def __init__(self) -> None:
+        self._paths: list[str] = []
+
+    def clear(self) -> None:
+        """Clear all registered paths. Useful for testing."""
+        self._paths.clear()
+        logger.debug("Schema path registry cleared")
+
+    def register(self, path: str) -> None:
+        """
+        Register a schema search path.
+
+        Args:
+            path: Directory path to search for schemas
+
+        Example:
+            import rem
+            rem.register_schema_path("/app/custom-agents")
+        """
+        if path not in self._paths:
+            self._paths.append(path)
+            logger.debug(f"Registered schema path: {path}")
+
+    def register_many(self, *paths: str) -> None:
+        """
+        Register multiple schema paths at once.
+
+        Example:
+            import rem
+            rem.register_schema_paths("/app/agents", "/app/evaluators")
+        """
+        for path in paths:
+            self.register(path)
+
+    def get_paths(self) -> list[str]:
+        """
+        Get all registered paths (registry + settings).
+
+        Returns paths in search order:
+        1. Programmatically registered paths (this registry)
+        2. Paths from SCHEMA__PATHS environment variable
+
+        Returns:
+            List of directory paths to search
+        """
+        from .settings import settings
+
+        # Combine registry paths with settings paths
+        all_paths = self._paths.copy()
+
+        # Add paths from settings (SCHEMA__PATHS env var)
+        for path in settings.schema_search.path_list:
+            if path not in all_paths:
+                all_paths.append(path)
+
+        return all_paths
+
+
+# =============================================================================
+# MODULE-LEVEL SINGLETONS
+# =============================================================================
+
+_model_registry = ModelRegistry()
+_schema_path_registry = SchemaPathRegistry()
+
+
+def register_model(
+    model: type[BaseModel] | None = None,
+    *,
+    table_name: str | None = None,
+    entity_key_field: str | None = None,
+) -> type[BaseModel] | Callable[[type[BaseModel]], type[BaseModel]]:
+    """
+    Register a Pydantic model for database schema generation.
+
+    Can be used as a decorator or called directly.
+
+    Example:
+        import rem
+
+        @rem.register_model
+        class CustomEntity(CoreModel):
+            name: str
+
+        # Or with options:
+        @rem.register_model(table_name="custom_table")
+        class AnotherEntity(CoreModel):
+            name: str
+
+        # Or direct call:
+        rem.register_model(MyModel, table_name="my_table")
+    """
+    def decorator(m: type[BaseModel]) -> type[BaseModel]:
+        return _model_registry.register(m, table_name, entity_key_field)
+
+    if model is not None:
+        return decorator(model)
+    return decorator
+
+
+def register_models(*models: type[BaseModel]) -> None:
+    """Register multiple models at once."""
+    _model_registry.register_many(*models)
+
+
+def get_model_registry() -> ModelRegistry:
+    """Get the global model registry instance."""
+    return _model_registry
+
+
+def clear_model_registry() -> None:
+    """Clear all model registrations. Useful for testing."""
+    _model_registry.clear()
+
+
+# =============================================================================
+# SCHEMA PATH FUNCTIONS
+# =============================================================================
+
+
+def register_schema_path(path: str) -> None:
+    """
+    Register a schema search path.
+
+    Paths registered here are searched BEFORE built-in package schemas.
+
+    Example:
+        import rem
+        rem.register_schema_path("/app/custom-agents")
+
+        # Now load_agent_schema("my-agent") will find /app/custom-agents/my-agent.yaml
+    """
+    _schema_path_registry.register(path)
+
+
+def register_schema_paths(*paths: str) -> None:
+    """
+    Register multiple schema paths at once.
+
+    Example:
+        import rem
+        rem.register_schema_paths("/app/agents", "/app/evaluators")
+    """
+    _schema_path_registry.register_many(*paths)
+
+
+def get_schema_path_registry() -> SchemaPathRegistry:
+    """Get the global schema path registry instance."""
+    return _schema_path_registry
+
+
+def get_schema_paths() -> list[str]:
+    """
+    Get all registered schema paths (registry + SCHEMA__PATHS env var).
+
+    Returns:
+        List of directory paths to search for schemas
+    """
+    return _schema_path_registry.get_paths()
+
+
+def clear_schema_path_registry() -> None:
+    """Clear all schema path registrations. Useful for testing."""
+    _schema_path_registry.clear()

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: