remdb 0.3.242__py3-none-any.whl

rem/models/entities/schema.py

@@ -0,0 +1,87 @@
+"""
+Schema - Agent schema definitions in REM.
+
+Schemas represent agent definitions that can be loaded into Pydantic AI.
+They store JsonSchema specifications that define agent capabilities, tools,
+and output structures.
+
+Schemas are used for:
+- Agent definition storage and versioning
+- Dynamic agent loading via X-Agent-Schema header
+- Agent registry and discovery
+- Schema validation and documentation
+- Ontology extraction configuration
+
+Key Fields:
+- name: Human-readable schema identifier
+- content: Markdown documentation and instructions
+- spec: JsonSchema specification (Pydantic model definition)
+- category: Schema classification (agent-type, workflow, ontology-extractor, etc.)
+- provider_configs: Optional LLM provider configurations (for multi-provider support)
+- embedding_fields: Fields in extracted_data that should be embedded for semantic search
+"""
+
+from typing import Optional
+
+from pydantic import Field
+
+from ..core import CoreModel
+
+
+class Schema(CoreModel):
+    """
+    Agent schema definition.
+
+    Schemas define agents that can be dynamically loaded into Pydantic AI.
+    They store JsonSchema specifications with embedded metadata for tools,
+    resources, and system prompts.
+
+    For ontology extraction agents:
+    - `provider_configs` enables multi-provider support (test across Anthropic, OpenAI, etc.)
+    - `embedding_fields` specifies which output fields should be embedded for semantic search
+
+    Tenant isolation is provided via CoreModel.tenant_id field.
+    """
+
+    name: str = Field(
+        ...,
+        description="Human-readable schema name (used as identifier)",
+    )
+
+    content: str = Field(
+        default="",
+        description="Markdown documentation and instructions for the schema",
+    )
+
+    spec: dict = Field(
+        ...,
+        description="JsonSchema specification defining the agent structure and capabilities",
+    )
+
+    category: Optional[str] = Field(
+        default=None,
+        description=(
+            "Schema category distinguishing schema types. "
+            "Values: 'agent' (AI agents), 'evaluator' (LLM-as-a-Judge evaluators). "
+            "Maps directly from json_schema_extra.kind field during ingestion."
+        ),
+    )
+
+    # Ontology extraction support
+    provider_configs: list[dict] = Field(
+        default_factory=list,
+        description=(
+            "Optional provider configurations for multi-provider testing. "
+            "Each dict has 'provider_name' and 'model_name'. "
+            "Example: [{'provider_name': 'anthropic', 'model_name': 'claude-sonnet-4-5'}]"
+        ),
+    )
+
+    embedding_fields: list[str] = Field(
+        default_factory=list,
+        description=(
+            "JSON paths in extracted_data to embed for semantic search. "
+            "Example: ['summary', 'candidate_name', 'skills'] for CV extraction. "
+            "Values will be concatenated and embedded using configured embedding provider."
+        ),
+    )

rem/models/entities/session.py

@@ -0,0 +1,84 @@
+"""
+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"
+    CLONE = "clone"
+
+
+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/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

@@ -0,0 +1,93 @@
+"""
+User - User entity in REM.
+
+Users represent people in the system, either as content creators,
+participants in moments, or entities referenced in resources.
+
+Users can be discovered through:
+- Entity extraction from resources
+- Moment present_persons lists
+- Direct user registration
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import Field
+
+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"
+    PRO = "pro"
+    SILVER = "silver"  # Deprecated? Keeping for backward compatibility if needed
+    GOLD = "gold"      # Deprecated? Keeping for backward compatibility if needed
+
+
+class User(CoreModel):
+    """
+    User entity.
+
+    Represents people in the REM system, either as active users
+    or entities extracted from content. Tenant isolation is provided
+    via CoreModel.tenant_id field.
+
+    Enhanced by dreaming worker:
+    - summary: Generated from activity analysis
+    - interests: Extracted from resources and sessions
+    - activity_level: Computed from recent engagement
+    - preferred_topics: Extracted from moment/resource topics
+    """
+
+    name: str = Field(
+        ...,
+        description="User name (human-readable, used as graph label)",
+        json_schema_extra={"entity_key": True},  # Primary business key for KV lookups
+    )
+    email: Optional[str] = Field(
+        default=None,
+        description="User email address",
+    )
+    role: Optional[str] = Field(
+        default=None,
+        description="User role (employee, contractor, external, etc.)",
+    )
+    tier: UserTier = Field(
+        default=UserTier.FREE,
+        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,
+        description="Security policy configuration (JSON, extensible for custom policies)",
+    )
+    summary: Optional[str] = Field(
+        default=None,
+        description="LLM-generated user profile summary (updated by dreaming worker)",
+    )
+    interests: list[str] = Field(
+        default_factory=list,
+        description="User interests extracted from activity",
+    )
+    preferred_topics: list[str] = Field(
+        default_factory=list,
+        description="Frequently discussed topics in kebab-case",
+    )
+    activity_level: Optional[str] = Field(
+        default=None,
+        description="Activity level: active, moderate, inactive",
+    )
+    last_active_at: Optional[datetime] = Field(
+        default=None,
+        description="Last activity timestamp",
+    )