remdb 0.3.146__py3-none-any.whl → 0.3.181__py3-none-any.whl

rem/api/mcp_router/tools.py

@@ -116,7 +116,8 @@ def mcp_tool_error_handler(func: Callable) -> Callable:
             # Otherwise wrap in success response
             return {"status": "success", **result}
         except Exception as e:
-            logger.error(f"{func.__name__} failed: {e}", exc_info=True)
+            # Use %s format to avoid issues with curly braces in error messages
+            logger.opt(exception=True).error("{} failed: {}", func.__name__, str(e))
             return {
                 "status": "error",
                 "error": str(e),
@@ -154,6 +155,10 @@ async def search_rem(
     - Fast exact match across all tables
     - Uses indexed label_vector for instant retrieval
     - Example: LOOKUP "Sarah Chen" returns all entities named "Sarah Chen"
+    - **Ontology Note**: Ontology content may contain markdown links like
+      `[sertraline](../../drugs/antidepressants/sertraline.md)`. The link name
+      (e.g., "sertraline") can be used as a LOOKUP subject, while the relative
+      path provides semantic context (e.g., it's a drug, specifically an antidepressant).
 
     **FUZZY** - Fuzzy text matching with similarity threshold:
     - Finds partial matches and typos
@@ -380,9 +385,10 @@ async def ask_rem_agent(
     from ...utils.schema_loader import load_agent_schema
 
     # Create agent context
+    # Note: tenant_id defaults to "default" if user_id is None
     context = AgentContext(
         user_id=user_id,
-        tenant_id=user_id,  # Set tenant_id to user_id for backward compat
+        tenant_id=user_id or "default",  # Use default tenant for anonymous users
         default_model=settings.llm.default_model,
     )
 
@@ -1040,3 +1046,172 @@ async def get_schema(
     logger.info(f"Retrieved schema for table '{table_name}' with {len(column_defs)} columns")
 
     return result
+
+
+@mcp_tool_error_handler
+async def save_agent(
+    name: str,
+    description: str,
+    properties: dict[str, Any] | None = None,
+    required: list[str] | None = None,
+    tools: list[str] | None = None,
+    tags: list[str] | None = None,
+    version: str = "1.0.0",
+    user_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    Save an agent schema to REM, making it available for use.
+
+    This tool creates or updates an agent definition in the user's schema space.
+    The agent becomes immediately available for conversations.
+
+    **Default Tools**: All agents automatically get `search_rem` and `register_metadata`
+    tools unless explicitly overridden.
+
+    Args:
+        name: Agent name in kebab-case (e.g., "code-reviewer", "sales-assistant").
+            Must be unique within the user's schema space.
+        description: The agent's system prompt. This is the full instruction set
+            that defines the agent's behavior, personality, and capabilities.
+            Use markdown formatting for structure.
+        properties: Output schema properties as a dict. Each property should have:
+            - type: "string", "number", "boolean", "array", "object"
+            - description: What this field captures
+            Example: {"answer": {"type": "string", "description": "Response to user"}}
+            If not provided, defaults to a simple {"answer": {"type": "string"}} schema.
+        required: List of required property names. Defaults to ["answer"] if not provided.
+        tools: List of tool names the agent can use. Defaults to ["search_rem", "register_metadata"].
+        tags: Optional tags for categorizing the agent.
+        version: Semantic version string (default: "1.0.0").
+        user_id: User identifier for scoping. Uses authenticated user if not provided.
+
+    Returns:
+        Dict with:
+        - status: "success" or "error"
+        - agent_name: Name of the saved agent
+        - version: Version saved
+        - message: Human-readable status
+
+    Examples:
+        # Create a simple agent
+        save_agent(
+            name="greeting-bot",
+            description="You are a friendly greeter. Say hello warmly.",
+            properties={"answer": {"type": "string", "description": "Greeting message"}},
+            required=["answer"]
+        )
+
+        # Create agent with structured output
+        save_agent(
+            name="sentiment-analyzer",
+            description="Analyze sentiment of text provided by the user.",
+            properties={
+                "answer": {"type": "string", "description": "Analysis explanation"},
+                "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
+                "confidence": {"type": "number", "minimum": 0, "maximum": 1}
+            },
+            required=["answer", "sentiment"],
+            tags=["analysis", "nlp"]
+        )
+    """
+    from ...agentic.agents.agent_manager import save_agent as _save_agent
+
+    # Get user_id from context if not provided
+    user_id = AgentContext.get_user_id_or_default(user_id, source="save_agent")
+
+    # Delegate to agent_manager
+    result = await _save_agent(
+        name=name,
+        description=description,
+        user_id=user_id,
+        properties=properties,
+        required=required,
+        tools=tools,
+        tags=tags,
+        version=version,
+    )
+
+    # Add helpful message for Slack users
+    if result.get("status") == "success":
+        result["message"] = f"Agent '{name}' saved. Use `/custom-agent {name}` to chat with it."
+
+    return result
+
+
+# =============================================================================
+# Test/Debug Tools (for development only)
+# =============================================================================
+
+@mcp_tool_error_handler
+async def test_error_handling(
+    error_type: Literal["exception", "error_response", "timeout", "success"] = "success",
+    delay_seconds: float = 0,
+    error_message: str = "Test error occurred",
+) -> dict[str, Any]:
+    """
+    Test tool for simulating different error scenarios.
+
+    **FOR DEVELOPMENT/TESTING ONLY** - This tool helps verify that error
+    handling works correctly through the streaming layer.
+
+    Args:
+        error_type: Type of error to simulate:
+            - "success": Returns successful response (default)
+            - "exception": Raises an exception (tests @mcp_tool_error_handler)
+            - "error_response": Returns {"status": "error", ...} dict
+            - "timeout": Delays for 60 seconds (simulates timeout)
+        delay_seconds: Optional delay before responding (0-10 seconds)
+        error_message: Custom error message for error scenarios
+
+    Returns:
+        Dict with test results or error information
+
+    Examples:
+        # Test successful response
+        test_error_handling(error_type="success")
+
+        # Test exception handling
+        test_error_handling(error_type="exception", error_message="Database connection failed")
+
+        # Test error response format
+        test_error_handling(error_type="error_response", error_message="Resource not found")
+
+        # Test with delay
+        test_error_handling(error_type="success", delay_seconds=2)
+    """
+    import asyncio
+
+    logger.info(f"test_error_handling called: type={error_type}, delay={delay_seconds}")
+
+    # Apply delay (capped at 10 seconds for safety)
+    if delay_seconds > 0:
+        await asyncio.sleep(min(delay_seconds, 10))
+
+    if error_type == "exception":
+        # This tests the @mcp_tool_error_handler decorator
+        raise RuntimeError(f"TEST EXCEPTION: {error_message}")
+
+    elif error_type == "error_response":
+        # This tests how the streaming layer handles error status responses
+        return {
+            "status": "error",
+            "error": error_message,
+            "error_code": "TEST_ERROR",
+            "recoverable": True,
+        }
+
+    elif error_type == "timeout":
+        # Simulate a very long operation (for testing client-side timeouts)
+        await asyncio.sleep(60)
+        return {"status": "success", "message": "Timeout test completed (should not reach here)"}
+
+    else:  # success
+        return {
+            "status": "success",
+            "message": "Test completed successfully",
+            "test_data": {
+                "error_type": error_type,
+                "delay_applied": delay_seconds,
+                "timestamp": str(asyncio.get_event_loop().time()),
+            },
+        }

rem/api/middleware/tracking.py

@@ -102,14 +102,14 @@ class AnonymousTrackingMiddleware(BaseHTTPMiddleware):
             # Tenant ID from header or default
             tenant_id = request.headers.get("X-Tenant-Id", "default")
 
-        # 4. Rate Limiting
-        if settings.postgres.enabled:
+        # 4. Rate Limiting (skip if disabled via settings)
+        if settings.postgres.enabled and settings.api.rate_limit_enabled:
             is_allowed, current, limit = await self.rate_limiter.check_rate_limit(
                 tenant_id=tenant_id,
                 identifier=identifier,
                 tier=tier
             )
-            
+
             if not is_allowed:
                 return JSONResponse(
                     status_code=429,
@@ -141,8 +141,8 @@ class AnonymousTrackingMiddleware(BaseHTTPMiddleware):
                 secure=settings.environment == "production"
             )
             
-        # Add Rate Limit headers
-        if settings.postgres.enabled and 'limit' in locals():
+        # Add Rate Limit headers (only if rate limiting is enabled)
+        if settings.postgres.enabled and settings.api.rate_limit_enabled and 'limit' in locals():
             response.headers["X-RateLimit-Limit"] = str(limit)
             response.headers["X-RateLimit-Remaining"] = str(max(0, limit - current))
             

rem/api/routers/auth.py

@@ -1,20 +1,71 @@
 """
-OAuth 2.1 Authentication Router.
+Authentication Router.
 
-Leverages Authlib for standards-compliant OAuth/OIDC implementation.
-Minimal custom code - Authlib handles PKCE, token validation, JWKS.
+Supports multiple authentication methods:
+1. Email (passwordless): POST /api/auth/email/send-code, POST /api/auth/email/verify
+2. OAuth (Google, Microsoft): GET /api/auth/{provider}/login, GET /api/auth/{provider}/callback
 
 Endpoints:
+- POST /api/auth/email/send-code     - Send login code to email
+- POST /api/auth/email/verify        - Verify code and create session
 - GET  /api/auth/{provider}/login    - Initiate OAuth flow
 - GET  /api/auth/{provider}/callback - OAuth callback
 - POST /api/auth/logout              - Clear session
 - GET  /api/auth/me                  - Current user info
 
 Supported providers:
+- email: Passwordless email login
 - google: Google OAuth 2.0 / OIDC
 - microsoft: Microsoft Entra ID OIDC
 
-Design Pattern (OAuth 2.1 + PKCE):
+=============================================================================
+Email Authentication Access Control
+=============================================================================
+
+The email auth provider implements a tiered access control system:
+
+Access Control Flow (send-code):
+    User requests login code
+    ├── User exists in database?
+    │   ├── Yes → Check user.tier
+    │   │   ├── tier == BLOCKED → Reject "Account is blocked"
+    │   │   └── tier != BLOCKED → Allow (send code, existing users grandfathered)
+    │   └── No (new user) → Check subscriber list first
+    │       ├── Email in subscribers table? → Allow (create user & send code)
+    │       └── Not a subscriber → Check EMAIL__TRUSTED_EMAIL_DOMAINS
+    │           ├── Setting configured → domain in trusted list?
+    │           │   ├── Yes → Create user & send code
+    │           │   └── No → Reject "Email domain not allowed for signup"
+    │           └── Not configured (empty) → Create user & send code (no restrictions)
+
+Key Behaviors:
+- Existing users: Always allowed to login (unless tier=BLOCKED)
+- Subscribers: Always allowed to login (regardless of email domain)
+- New users: Must have email from trusted domain (if EMAIL__TRUSTED_EMAIL_DOMAINS is set)
+- No restrictions: Leave EMAIL__TRUSTED_EMAIL_DOMAINS empty to allow all domains
+
+User Tiers (models.entities.UserTier):
+- BLOCKED: Cannot login (rejected at send-code)
+- ANONYMOUS: Rate-limited anonymous access
+- FREE: Standard free tier
+- BASIC/PRO: Paid tiers with additional features
+
+Configuration:
+    # Allow only specific domains for new signups
+    EMAIL__TRUSTED_EMAIL_DOMAINS=siggymd.ai,example.com
+
+    # Allow all domains (no restrictions)
+    EMAIL__TRUSTED_EMAIL_DOMAINS=
+
+Example blocking a user:
+    user = await user_repo.get_by_id(user_id, tenant_id="default")
+    user.tier = UserTier.BLOCKED
+    await user_repo.upsert(user)
+
+=============================================================================
+OAuth Design Pattern (OAuth 2.1 + PKCE)
+=============================================================================
+
 1. User clicks "Login with Google"
 2. /login generates state + PKCE code_verifier
 3. Store code_verifier in session
@@ -37,6 +88,7 @@ Environment variables:
     AUTH__MICROSOFT__CLIENT_ID=<microsoft-client-id>
     AUTH__MICROSOFT__CLIENT_SECRET=<microsoft-client-secret>
     AUTH__MICROSOFT__TENANT=common
+    EMAIL__TRUSTED_EMAIL_DOMAINS=example.com  # Optional: restrict new signups
 
 References:
 - Authlib: https://docs.authlib.org/en/latest/
@@ -46,11 +98,15 @@ References:
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import RedirectResponse
 from authlib.integrations.starlette_client import OAuth
+from pydantic import BaseModel, EmailStr
 from loguru import logger
 
 from ...settings import settings
 from ...services.postgres.service import PostgresService
 from ...services.user_service import UserService
+from ...auth.providers.email import EmailAuthProvider
+from ...auth.jwt import JWTService, get_jwt_service
+from ...utils.user_id import email_to_user_id
 
 router = APIRouter(prefix="/api/auth", tags=["auth"])
 
@@ -87,6 +143,182 @@ if settings.auth.microsoft.client_id:
     logger.info(f"Microsoft OAuth provider registered (tenant: {tenant})")
 
 
+# =============================================================================
+# Email Authentication Endpoints
+# =============================================================================
+
+
+class EmailSendCodeRequest(BaseModel):
+    """Request to send login code."""
+    email: EmailStr
+
+
+class EmailVerifyRequest(BaseModel):
+    """Request to verify login code."""
+    email: EmailStr
+    code: str
+
+
+@router.post("/email/send-code")
+async def send_email_code(request: Request, body: EmailSendCodeRequest):
+    """
+    Send a login code to an email address.
+
+    Creates user if not exists (using deterministic UUID from email).
+    Stores code in user metadata with expiry.
+
+    Args:
+        request: FastAPI request
+        body: EmailSendCodeRequest with email
+
+    Returns:
+        Success status and message
+    """
+    if not settings.email.is_configured:
+        raise HTTPException(
+            status_code=501,
+            detail="Email authentication is not configured"
+        )
+
+    # Get database connection
+    if not settings.postgres.enabled:
+        raise HTTPException(
+            status_code=501,
+            detail="Database is required for email authentication"
+        )
+
+    db = PostgresService()
+    try:
+        await db.connect()
+
+        # Initialize email auth provider
+        email_auth = EmailAuthProvider()
+
+        # Send code
+        result = await email_auth.send_code(
+            email=body.email,
+            db=db,
+        )
+
+        if result.success:
+            return {
+                "success": True,
+                "message": result.message,
+                "email": result.email,
+            }
+        else:
+            raise HTTPException(
+                status_code=400,
+                detail=result.message or result.error
+            )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error sending login code: {e}")
+        raise HTTPException(status_code=500, detail="Failed to send login code")
+    finally:
+        await db.disconnect()
+
+
+@router.post("/email/verify")
+async def verify_email_code(request: Request, body: EmailVerifyRequest):
+    """
+    Verify login code and create session with JWT tokens.
+
+    Args:
+        request: FastAPI request
+        body: EmailVerifyRequest with email and code
+
+    Returns:
+        Success status with user info and JWT tokens
+    """
+    if not settings.email.is_configured:
+        raise HTTPException(
+            status_code=501,
+            detail="Email authentication is not configured"
+        )
+
+    if not settings.postgres.enabled:
+        raise HTTPException(
+            status_code=501,
+            detail="Database is required for email authentication"
+        )
+
+    db = PostgresService()
+    try:
+        await db.connect()
+
+        # Initialize email auth provider
+        email_auth = EmailAuthProvider()
+
+        # Verify code
+        result = await email_auth.verify_code(
+            email=body.email,
+            code=body.code,
+            db=db,
+        )
+
+        if not result.success:
+            raise HTTPException(
+                status_code=400,
+                detail=result.message or result.error
+            )
+
+        # Create session - compatible with OAuth session format
+        user_dict = email_auth.get_user_dict(
+            email=result.email,
+            user_id=result.user_id,
+        )
+
+        # Fetch actual user data from database to get role/tier
+        user_service = UserService(db)
+        try:
+            user_entity = await user_service.get_user_by_id(result.user_id)
+            if user_entity:
+                # Override defaults with actual database values
+                user_dict["role"] = user_entity.role or "user"
+                user_dict["roles"] = [user_entity.role] if user_entity.role else ["user"]
+                user_dict["tier"] = user_entity.tier.value if user_entity.tier else "free"
+                user_dict["name"] = user_entity.name or user_dict["name"]
+        except Exception as e:
+            logger.warning(f"Could not fetch user details: {e}")
+            # Continue with defaults from get_user_dict
+
+        # Generate JWT tokens
+        jwt_service = get_jwt_service()
+        tokens = jwt_service.create_tokens(user_dict)
+
+        # Store user in session (for backward compatibility)
+        request.session["user"] = user_dict
+
+        logger.info(f"User authenticated via email: {result.email}")
+
+        return {
+            "success": True,
+            "message": result.message,
+            "user": user_dict,
+            # JWT tokens for stateless auth
+            "access_token": tokens["access_token"],
+            "refresh_token": tokens["refresh_token"],
+            "token_type": tokens["token_type"],
+            "expires_in": tokens["expires_in"],
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error verifying login code: {e}")
+        raise HTTPException(status_code=500, detail="Failed to verify login code")
+    finally:
+        await db.disconnect()
+
+
+# =============================================================================
+# OAuth Authentication Endpoints
+# =============================================================================
+
+
 @router.get("/{provider}/login")
 async def login(provider: str, request: Request):
     """
@@ -201,8 +433,9 @@ async def callback(provider: str, request: Request):
                     await user_service.link_anonymous_session(user_entity, anon_id)
                     
                 # Enrich session user with DB info
+                # user_id = UUID5 hash of email (deterministic, bijection)
                 db_info = {
-                    "id": str(user_entity.id),
+                    "id": email_to_user_id(user_info.get("email")),
                     "tenant_id": user_entity.tenant_id,
                     "tier": user_entity.tier.value if user_entity.tier else "free",
                     "roles": [user_entity.role] if user_entity.role else [],
@@ -268,7 +501,7 @@ async def logout(request: Request):
 @router.get("/me")
 async def me(request: Request):
     """
-    Get current user information from session.
+    Get current user information from session or JWT.
 
     Args:
         request: FastAPI request
@@ -276,6 +509,16 @@ async def me(request: Request):
     Returns:
         User information or 401 if not authenticated
     """
+    # First check for JWT in Authorization header
+    auth_header = request.headers.get("Authorization")
+    if auth_header and auth_header.startswith("Bearer "):
+        token = auth_header[7:]
+        jwt_service = get_jwt_service()
+        user = jwt_service.verify_token(token)
+        if user:
+            return user
+
+    # Fall back to session
     user = request.session.get("user")
     if not user:
         raise HTTPException(status_code=401, detail="Not authenticated")
@@ -283,6 +526,69 @@ async def me(request: Request):
     return user
 
 
+# =============================================================================
+# JWT Token Endpoints
+# =============================================================================
+
+
+class TokenRefreshRequest(BaseModel):
+    """Request to refresh access token."""
+    refresh_token: str
+
+
+@router.post("/token/refresh")
+async def refresh_token(body: TokenRefreshRequest):
+    """
+    Refresh access token using refresh token.
+
+    Args:
+        body: TokenRefreshRequest with refresh_token
+
+    Returns:
+        New access token or 401 if refresh token is invalid
+    """
+    jwt_service = get_jwt_service()
+    result = jwt_service.refresh_access_token(body.refresh_token)
+
+    if not result:
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid or expired refresh token"
+        )
+
+    return result
+
+
+@router.post("/token/verify")
+async def verify_token(request: Request):
+    """
+    Verify an access token is valid.
+
+    Pass the token in the Authorization header: Bearer <token>
+
+    Returns:
+        User info if valid, 401 if invalid
+    """
+    auth_header = request.headers.get("Authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(
+            status_code=401,
+            detail="Missing Authorization header"
+        )
+
+    token = auth_header[7:]
+    jwt_service = get_jwt_service()
+    user = jwt_service.verify_token(token)
+
+    if not user:
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid or expired token"
+        )
+
+    return {"valid": True, "user": user}
+
+
 # =============================================================================
 # Development Token Endpoints (non-production only)
 # =============================================================================
@@ -351,3 +657,43 @@ async def get_dev_token(request: Request):
         "usage": f'curl -H "Authorization: Bearer {token}" http://localhost:8000/api/v1/...',
         "warning": "This token is for development/testing only and will not work in production.",
     }
+
+
+@router.get("/dev/mock-code/{email}")
+async def get_mock_code(email: str, request: Request):
+    """
+    Get the mock login code for testing (non-production only).
+
+    This endpoint retrieves the code that was "sent" via email in mock mode.
+    Use this for automated testing without real email delivery.
+
+    Usage:
+        1. POST /api/auth/email/send-code with email
+        2. GET /api/auth/dev/mock-code/{email} to retrieve the code
+        3. POST /api/auth/email/verify with email and code
+
+    Returns:
+        401 if in production environment
+        404 if no code found for the email
+        The code and email otherwise
+    """
+    if settings.environment == "production":
+        raise HTTPException(
+            status_code=401,
+            detail="Mock codes are not available in production"
+        )
+
+    from ...services.email import EmailService
+
+    code = EmailService.get_mock_code(email)
+    if not code:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No mock code found for {email}. Send a code first."
+        )
+
+    return {
+        "email": email,
+        "code": code,
+        "warning": "This endpoint is for testing only and will not work in production.",
+    }